neo.mjs 10.0.0-beta.2 → 10.0.0-beta.3

package/learn/guides/CustomComponents.md

@@ -1,45 +1,287 @@
 ## Introduction
 
-Neo.mjs is class-based, which means you're free to extend any component (or any other Neo.mjs class).
+A major strength of Neo.mjs is its extensive library of components. In most cases, you can build sophisticated
+user interfaces simply by creating configuration objects for these existing components and adding them to a container's
+`items` array. This configuration-driven approach is a significant departure from frameworks like Angular, React, or
+Vue, where creating custom components is a core part of the development workflow.
 
+However, there are times when you need to create something truly unique or encapsulate a specific set of configurations
+and logic for reuse. In these scenarios, creating a custom component by extending a framework class is the perfect
+solution.
 
-## Overriding ancestor configs
+This guide will walk you through the process.
 
-## Introducing new configs
+## Choosing the Right Base Class
 
-## Lifecycle config properties
+In the world of React, developers often use Higher-Order Components (HOCs) to reuse component logic. In Neo.mjs, you
+achieve a similar result through class extension. The key to creating a robust and efficient custom component is
+choosing the correct base class to extend.
+
+Instead of extending the most generic `Neo.component.Base` class, look for a more specialized class that already
+provides the functionality you need.
+
+-   If your component needs to contain other components, extend `Neo.container.Base`.
+-   If you're creating an interactive element, extending `Neo.button.Base` gives you focus and keyboard support.
+-   If you need a custom form field, look for a suitable class within `Neo.form.field`.
+
+By choosing the most specific base class, you inherit a rich set of features, saving you from having to reinvent the
+wheel and ensuring your component integrates smoothly into the framework.
+
+## Real-World Examples inside the Neo.mjs Component Library
+
+The Neo.mjs framework itself uses this principle of extending the most specific class. Let's look at a couple of
+examples from the framework's source code.
+
+### Toolbar Inheritance
+
+-   **`Neo.toolbar.Base`** extends `Neo.container.Base`.
+    It's the foundational toolbar and extends `Container` because its main purpose is to hold other components. It adds
+    features like docking.
+
+-   **`Neo.tab.header.Toolbar`** extends `Neo.toolbar.Base`.
+    This is a specialized toolbar for tab headers. It inherits the ability to hold items and be docked, and adds new
+    logic for managing the active tab indicator.
+
+-   **`Neo.grid.header.Toolbar`** extends `Neo.toolbar.Base`.
+    This toolbar is for grid headers. It also inherits from `toolbar.Base` and adds grid-specific features like column
+    resizing and reordering.
+
+### Button Inheritance
+
+-   **`Neo.button.Base`** extends `Neo.component.Base`.
+    This is the basic button, providing core features like click handling and icon support.
+
+-   **`Neo.tab.header.Button`** extends `Neo.button.Base`.
+    A button used in tab headers. It inherits all the standard button features and adds a visual indicator for the
+    active tab.
+
+-   **`Neo.grid.header.Button`** extends `Neo.button.Base`.
+    A button for grid column headers. It inherits from the base button and adds features for sorting and filtering the
+    grid data.
+
+These examples show how building on top of specialized base classes leads to a clean, maintainable, and powerful
+component architecture.
+
+## The Role of `Neo.setupClass()` and the Global `Neo` Namespace
+
+When you define a class in Neo.mjs and pass it to `Neo.setupClass()`, the framework does more than just process its configurations and apply mixins. A crucial step performed by `Neo.setupClass()` is to **enhance the global `Neo` namespace** with a reference to your newly defined class.
+
+This means that after `Neo.setupClass(MyClass)` is executed, your class becomes accessible globally via `Neo.[your.class.name]`, where `[your.class.name]` corresponds to the `className` config you defined (e.g., `Neo.button.Base`, `Neo.form.field.Text`).
+
+**Implications for Class Extension and Usage:**
+
+*   **Global Accessibility**: You can refer to any framework class (or your own custom classes after they've been set up) using their full `Neo` namespace path (e.g., `Neo.button.Base`, `Neo.container.Base`) anywhere in your application code, even without an explicit ES module import for that specific class.
+*   **Convenience vs. Best Practice**: While `extends Neo.button.Base` might technically work without an `import Button from '...'`, it is generally **not recommended** for application code. Explicit ES module imports (e.g., `import Button from '../button/Base.mjs';`) are preferred because they:
+    *   **Improve Readability**: Clearly show the dependencies of your module.
+    *   **Enhance Tooling**: Enable better static analysis, auto-completion, and refactoring support in modern IDEs.
+    *   **Ensure Consistency**: Promote a consistent and predictable coding style.
+*   **Framework Internal Use**: The global `Neo` namespace is heavily utilized internally by the framework itself for its class registry, dependency resolution, and dynamic instantiation (e.g., when using `ntype` or `module` configs).
+
+Understanding this mechanism clarifies how Neo.mjs manages its class system and provides the underlying flexibility for its configuration-driven approach.
+
+## Overriding Ancestor Configs
+
+The simplest way to create a custom component is to extend an existing one and override some of its default
+configuration values.
+
+Every class in Neo.mjs has a `static config` block where its properties are defined. When you extend a class, you can
+define your own `static config` block and set new default values for any property inherited from an ancestor class.
+
+In the example below, we create `MySpecialButton` by extending `Neo.button.Base`. We then override the `iconCls` and
+`ui` configs to create a button with a specific look and feel.
+
+## Introducing New Configs
+
+You can also add entirely new configuration properties to your custom components. To make a config "reactive" – meaning
+it automatically triggers a lifecycle method when its value changes – you **must** define it with a trailing underscore (`_`).
+
+For a reactive config like `myConfig_`, the framework provides this behavior:
+- **Reading**: You can access the value directly: `this.myConfig`.
+- **Writing**: Assigning a new value (`this.myConfig = 'new value'`) triggers a prototype-based setter. This is the core of Neo.mjs reactivity.
+- **Hooks**: The framework provides three optional hooks for each reactive config: `beforeGet`, `beforeSet`, and `afterSet`. After a value is set, the `afterSetMyConfig(value, oldValue)` method is automatically called.
+
+If you define a config without the trailing underscore, it will simply be a static property on the class instance and will not trigger any lifecycle methods.
+
+For a complete explanation of the config system, including details on all the lifecycle hooks, please see the [Unified Config System guide](benefits.ConfigSystem).
+
+## Example: A Custom Button
+
+Let's look at a practical example. Here, we'll create a custom button that combines the standard `text` config with a new
+`specialText_` config to create a dynamic label.
 
 ```javascript live-preview
-import Button from '../button/Base.mjs';
-// In practice this would be some handy reusable component
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+
+// 1. Define our custom component by extending a framework class.
 class MySpecialButton extends Button {
     static config = {
         className: 'Example.view.MySpecialButton',
-        iconCls  : 'far fa-face-grin-wide',
-        ui       : 'ghost'
+
+        // a. Override configs from the parent class
+        iconCls: 'far fa-face-grin-wide',
+        ui     : 'ghost',
+
+        // b. Add a new reactive config (note the trailing underscore)
+        specialText_: 'I am special'
+    }
+
+    // c. Hook into the component lifecycle
+    afterSetSpecialText(value, oldValue) {
+        this.updateButtonText()
+    }
+
+    afterSetText(value, oldValue) {
+        this.updateButtonText()
+    }
+
+    // d. A custom method to update the button's text
+    updateButtonText() {
+        const {specialText, text} = this;
+        let fullText = `${text} (${specialText})`;
+
+        // Directly manipulate the VDom text node and update the component
+        this.textNode.text = fullText;
+        this.update();
     }
 }
 
 MySpecialButton = Neo.setupClass(MySpecialButton);
 
 
-import Container from '../container/Base.mjs';
-
+// 2. Use the new component in a view.
 class MainView extends Container {
     static config = {
         className: 'Example.view.MainView',
-        layout   : {ntype:'vbox', align:'start'},
+        layout   : {ntype: 'vbox', align: 'start'},
         items    : [{
+            // A standard framework button for comparison
             module : Button,
             iconCls: 'fa fa-home',
             text   : 'A framework button'
         }, {
-            module : MySpecialButton,
-            text   : 'My special button'
+            // Our new custom button
+            module     : MySpecialButton,
+            text       : 'My button',
+            specialText: 'is very special'
+        }]
+    }
+}
+
+MainView = Neo.setupClass(MainView);
+```
+
+### Breakdown of the Example:
+
+1.  **Class Definition**: We define `MySpecialButton` which `extends` the framework's `Button` class.
+2.  **New Reactive Config**: We add a `specialText_` config. The trailing underscore makes it reactive.
+3.  **Lifecycle Methods**: We implement `afterSetSpecialText()` and override `afterSetText()` to call our custom
+    `updateButtonText()` method. Because `afterSet` hooks are called for initial values upon instantiation, this
+    ensures the button text is correct from the start and stays in sync.
+4.  **Custom Method**: The `updateButtonText()` method combines the `text` and `specialText` configs and updates the
+    `text` property of the button's `textNode` in the VDOM.
+5.  **`this.update()`**: After changing the VDOM, we call `this.update()` to make the framework apply our changes to the
+    real DOM.
+
+This example shows how you can create a component that encapsulates its own logic and provides a richer, more dynamic
+behavior than a standard component.
+
+## Extending `Component.Base`: Building VDom from Scratch
+
+While extending specialized components like `Button` or `Container` is common for adding features (acting like a
+Higher-Order Component), there are times when you need to define a component's HTML structure from the ground up. For
+this, you extend the generic `Neo.component.Base`.
+
+When you extend `component.Base`, you are responsible for defining the component's entire virtual DOM (VDom) structure
+using the `vdom` config. This gives you complete control over the rendered output.
+
+### Example: A Simple Profile Badge
+
+Let's create a `ProfileBadge` component that displays a user's name and an online status indicator.
+
+```javascript live-preview
+import Component from '../component/Base.mjs';
+import Container from '../container/Base.mjs';
+import NeoArray  from '../util/Array.mjs';
+import VdomUtil  from '../util/Vdom.mjs';
+
+// 1. Extend the generic Component.Base
+class ProfileBadge extends Component {
+    static config = {
+        className: 'Example.view.ProfileBadge',
+        ntype    : 'profile-badge',
+
+        // a. Define the VDom from scratch
+        vdom: {
+            cls: ['profile-badge'],
+            cn : [
+                {tag: 'span', cls: ['status-indicator'], flag: 'statusNode'},
+                {tag: 'span', cls: ['username'],         flag: 'usernameNode'}
+            ]
+        },
+
+        // b. Add new reactive configs to control the component (note the trailing underscore)
+        online_  : false,
+        username_: 'Guest'
+    }
+
+    // d. Define getters for easy access to flagged VDom nodes
+    get statusNode() {
+        return VdomUtil.getByFlag(this.vdom, 'statusNode')
+    }
+
+    get usernameNode() {
+        return VdomUtil.getByFlag(this.vdom, 'usernameNode')
+    }
+
+    // c. Use lifecycle methods to react to config changes
+    afterSetOnline(value, oldValue) {
+        // Access the VDom node via the getter
+        NeoArray.toggle(this.statusNode.cls, 'online', value);
+        this.update() // Trigger a VDom update
+    }
+
+    afterSetUsername(value, oldValue) {
+        this.usernameNode.text = value;
+        this.update()
+    }
+}
+
+ProfileBadge = Neo.setupClass(ProfileBadge);
+
+
+// 2. Use the new component
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype: 'vbox', align: 'start'},
+        items    : [{
+            module  : ProfileBadge,
+            username: 'Alice',
+            online  : true
+        }, {
+            module  : ProfileBadge,
+            username: 'Bob',
+            online  : false,
+            style   : {marginTop: '10px'}
         }]
     }
 }
 
-Neo.setupClass(MainView);
+MainView= Neo.setupClass(MainView);
 ```
 
+### Key Differences in this Approach:
+
+1.  **Base Class**: We extend `Neo.component.Base` because we are not inheriting complex logic like a `Button` or
+    `Container`.
+2.  **`vdom` Config**: We define the entire HTML structure inside the `vdom` config. We use `flag`s (`statusNode`,
+    `usernameNode`) to easily reference these VDom nodes later.
+3.  **Lifecycle Methods**: We use `afterSet...` methods to react to changes in our custom `online_` and `username_`
+    configs. Inside these methods, we directly manipulate the properties of our VDom nodes and then call `this.update()`
+    to apply the changes to the real DOM.
+
+This approach gives you maximum control, but it also means you are responsible for building the structure yourself.
+
+For a deeper dive into advanced VDom manipulation, including performance best practices and security, please refer to the
+[Working with VDom guide](guides.WorkingWithVDom).

package/learn/guides/ExtendingNeoClasses.md

@@ -0,0 +1,331 @@
+# 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 application logic.
+
+This guide covers the universal principles of class extension in Neo.mjs, which apply across all class types, not just UI components.
+
+## 1. The `static config` Block: Defining Properties
+
+Every Neo.mjs class utilizes a `static config` block. This is where you define the properties that instances of your class will possess. These properties can be simple values, objects, or even other Neo.mjs class configurations.
+
+```javascript readonly
+class MyBaseClass extends Neo.core.Base {
+    static config = {
+        className: 'My.Base.Class', // Unique identifier for the class
+        myString : 'Hello',
+        myNumber : 123
+    }
+}
+
+export default Neo.setupClass(MyBaseClass);
+```
+
+Common configs you'll encounter include `className` (a unique string identifier for your class) and `ntype` (a shorthand alias for component creation).
+
+## 2. Reactive Configs: The Trailing Underscore (`_`)
+
+A cornerstone of Neo.mjs's reactivity is the trailing underscore (`_`) convention for configs defined in `static config`. When you append an underscore to a config name (e.g., `myConfig_`), the framework automatically generates a reactive getter and setter for it.
+
+```javascript readonly
+class MyReactiveClass extends Neo.core.Base {
+    static config = {
+        className        : 'My.Reactive.Class',
+        myReactiveConfig_: 'initial value' // This config is reactive
+    }
+
+    onConstructed() {
+        super.onConstructed();
+        console.log(this.myReactiveConfig);  // Accesses the getter
+        this.myReactiveConfig = 'new value'; // Triggers the setter
+    }
+}
+
+export default Neo.setupClass(MyReactiveClass);
+```
+
+Assigning a new value to a reactive property (e.g., `this.myReactiveProp = 'new value'`) triggers its setter, which in turn can invoke lifecycle hooks, enabling automatic updates and side effects. Properties without the underscore are static and do not trigger this reactive behavior.
+
+## 3. Configuration Lifecycle Hooks (`beforeSet`, `afterSet`, `beforeGet`)
+
+For every reactive config (`myConfig_`), Neo.mjs provides three optional lifecycle hooks that you can implement in your class. These methods are automatically called by the framework during the config's lifecycle, offering powerful interception points:
+
+*   **`beforeSetMyConfig(value, oldValue)`**:
+    *   **Purpose**: Intercepts the value *before* it is set. Ideal for validation, type coercion, or transforming the incoming value.
+    *   **Return Value**: Return the (potentially modified) `value` that should be set. Returning `undefined` or `null` will prevent the value from being set.
+
+*   **`afterSetMyConfig(value, oldValue)`**:
+    *   **Purpose**: Executed *after* the value has been successfully set. Ideal for triggering side effects, updating the UI (e.g., calling `this.update()` for components), or firing events.
+    *   **Return Value**: None.
+
+*   **`beforeGetMyConfig(value)`**:
+    *   **Purpose**: Intercepts the value *before* it is returned by the getter. Useful for lazy initialization, computing values on demand, or returning a transformed version of the stored value.
+    *   **Return Value**: Return the `value` that should be returned by the getter.
+
+### Overriding Lifecycle Hooks: `super` vs. Full Override
+
+When extending a Neo.mjs class, you often need to customize the behavior of inherited lifecycle hooks (like `afterSet*`, `onConstructed`, etc.). You have two primary approaches:
+
+#### 1. Extending Parent Behavior (Calling `super`)
+
+This is the most common and recommended approach. By calling `super.methodName(...)`, you ensure that the parent class's implementation of the hook is executed. You can then add your custom logic either before or after the `super` call.
+
+This approach is crucial for maintaining the framework's intended behavior and ensuring that inherited features continue to function correctly.
+
+```javascript readonly
+import Button from '../../src/button/Base.mjs';
+
+class MyExtendedButton extends Button {
+    static config = {
+        className: 'My.Extended.Component',
+        // text_ config is inherited from Button.Base
+        // We can set a default value here if needed, or rely on button.Base's default
+        text: 'New Default Text'
+    }
+
+    // Example: Adding logic after the parent's afterSetText
+    afterSetText(value, oldValue) {
+        //  Add your custom pre-processing logic here
+        super.afterSetText(value, oldValue);
+        console.log(`Custom logic: Button text changed to "${value}"`);
+        // Add your custom post-processing logic here
+    }
+}
+
+export default Neo.setupClass(MyExtendedButton);
+```
+
+#### 2. Completely Overriding Parent Behavior (No `super` Call)
+
+In rare cases, you might want to completely replace the parent class's implementation of a hook. This is achieved by simply omitting the `super` call within your overridden method.
+
+**Caution**: Use this approach with extreme care. You must fully understand the parent's implementation and ensure that your override does not break essential framework functionality or inherited features. This is generally reserved for advanced scenarios where you need full control over the hook's execution.
+
+```javascript readonly
+import Button from '../../src/button/Base.mjs';
+
+class MyFullyOverriddenButton extends Button {
+    static config = {
+        className: 'My.Fully.Overridden.Component',
+        text     : 'New Default Text'
+    }
+
+    // Example: Completely overriding afterSetText
+    afterSetText(value, oldValue) {
+        // No super.afterSetText(value, oldValue); call
+        console.log(`Fully custom logic: Button text changed to "${value}"`);
+        // The parent's afterSetText will NOT be executed
+        // This means that in this case you need to take care on your own to map the text value to the vdom.
+    }
+}
+
+export default Neo.setupClass(MyFullyOverriddenButton);
+```
+
+
+
+```javascript readonly
+class MyHookedClass extends Neo.core.Base {
+    static config = {
+        className: 'My.Hooked.Class',
+        myValue_ : 0
+    }
+
+    beforeSetMyValue(value, oldValue) {
+        if (typeof value !== 'number' || value < 0) {
+            console.warn('myValue must be a non-negative number!');
+            return 0; // Default to 0 if invalid
+        }
+        return value;
+    }
+
+    afterSetMyValue(value, oldValue) {
+        console.log(`myValue changed from ${oldValue} to ${value}`);
+        // In a component, you might call this.update() here
+    }
+
+    beforeGetMyValue(value) {
+        // Example: lazy initialization or computed value
+        if (value === 0 && !this._initialized) {
+            console.log('Initializing myValue on first access');
+            this._initialized = true;
+            return 10; // Return a default initial value
+        }
+        return value;
+    }
+}
+
+export default Neo.setupClass(MyHookedClass);
+```
+
+## 4. The Role of `Neo.setupClass()` and the Global `Neo` Namespace
+
+When you define a class in Neo.mjs and pass it to `Neo.setupClass()`, the framework performs several crucial operations. One of the most significant is to **enhance the global `Neo` namespace** with a reference to your newly defined class.
+
+This means that after `Neo.setupClass(MyClass)` is executed, your class becomes accessible globally via `Neo.[your.class.name]`, where `[your.class.name]` corresponds to the `className` config you defined (e.g., `Neo.button.Base`, `Neo.form.field.Text`, or your custom `My.Custom.Class`).
+
+**Implications for Class Extension and Usage:**
+
+*   **Global Accessibility**: You can refer to any framework class (or your own custom classes after they've been set up) using their full `Neo` namespace path (e.g., `Neo.button.Base`, `Neo.container.Base`) anywhere in your application code, even without an explicit ES module import for that specific class.
+*   **Convenience vs. Best Practice**: While `extends Neo.button.Base` might technically work without an `import Button from '...'`, it is generally **not recommended** for application code. Explicit ES module imports (e.g., `import Button from '../button/Base.mjs';`) are preferred because they:
+    *   **Improve Readability**: Clearly show the dependencies of your module.
+    *   **Enhance Tooling**: Enable better static analysis, auto-completion, and refactoring support in modern IDEs.
+    *   **Ensure Consistency**: Promote a consistent and predictable coding style.
+*   **Framework Internal Use**: The global `Neo` namespace is heavily utilized internally by the framework itself for its class registry, dependency resolution, and dynamic instantiation (e.g., when using `ntype` or `module` configs).
+
+Understanding this mechanism clarifies how Neo.mjs manages its class system and provides the underlying flexibility for its configuration-driven approach.
+
+## 5. Practical Examples: Models, Stores, and Controllers
+
+The principles of class extension apply universally across all Neo.mjs class types.
+
+### Extending `Neo.data.Model`
+
+Models define the structure and behavior of individual data records. While reactive configs can be used for class-level properties of a Model (e.g., a global setting for all products), properties that vary per record (like `price` or `discount`) should be defined as fields within the `fields` array. Neo.mjs provides `convert` and `calculate` functions directly on field definitions for per-record logic.
+
+```javascript readonly
+import Model from '../../src/data/Model.mjs';
+
+class ProductModel extends Model {
+    static config = {
+        className: 'App.model.Product',
+        fields: [
+            {name: 'id',    type: 'Number'},
+            {name: 'name',  type: 'String'},
+            {name: 'price', type: 'Number', defaultValue: 0,
+                // Use a convert function for field-level validation or transformation
+                convert: value => {
+                    if (typeof value !== 'number' || value < 0) {
+                        console.warn('Price field must be a non-negative number!');
+                        return 0;
+                    }
+                    return value;
+                }
+            },
+            {name: 'discount', type: 'Number', defaultValue: 0,
+                // Use a convert function for field-level validation or transformation
+                convert: value => {
+                    if (typeof value !== 'number' || value < 0 || value > 1) {
+                        console.warn('Discount field must be a number between 0 and 1!');
+                        return 0;
+                    }
+                    return value;
+                }
+            },
+            {name: 'discountedPrice', type: 'Number',
+                // Use a calculate function for derived values based on other fields in the record
+                calculate: (data) => {
+                    // 'data' contains the raw field values of the current record
+                    return data.price * (1 - data.discount);
+                }
+            }
+        ]
+    }
+}
+
+Neo.setupClass(ProductModel);
+```
+
+### Extending `Neo.data.Store`
+
+Stores manage collections of data records, often using a defined `Model`.
+
+```javascript readonly
+import Store        from '../../src/data/Store.mjs';
+import ProductModel from './ProductModel.mjs'; // Assuming ProductModel is in the same directory
+
+class ProductsStore extends Store {
+    static config = {
+        className: 'App.store.Products',
+        model    : ProductModel, // Use our custom ProductModel
+        autoLoad : true,
+        url      : '/api/products', // Example API endpoint
+        sorters  : [{
+            property : 'name',
+            direction: 'ASC'
+        }]
+    }
+
+    // Custom method to filter by price range
+    filterByPriceRange(min, max) {
+        // The idiomatic way to apply filters is by setting the 'filters' config.
+        // This replaces any existing filters.
+        this.filters = [{
+            property: 'price',
+            operator: '>=',
+            value   : min
+        }, {
+            property: 'price',
+            operator: '<=',
+            value   : max
+        }];
+    }
+
+    // To add filters without replacing existing ones, you would typically
+    // read the current filters, add new ones, and then set the filters config.
+    // Example (conceptual, not part of the class):
+    /*
+    addPriceRangeFilter(min, max) {
+        const currentFilters = this.filters ? [...this.filters] : [];
+        currentFilters.push({
+            property: 'price',
+            operator: '>=',
+            value   : min
+        }, {
+            property: 'price',
+            operator: '<=',
+            value   : max
+        });
+        this.filters = currentFilters;
+    }
+    */
+}
+
+Neo.setupClass(ProductsStore);
+```
+
+### Extending `Neo.controller.Component`
+
+Controllers encapsulate logic related to components, often handling events or managing state.
+
+```javascript readonly
+import ComponentController from '../../src/controller/Component.mjs';
+
+class MyCustomController extends ComponentController {
+    static config = {
+        className: 'App.controller.MyCustom',
+        // A reactive property to manage a piece of controller-specific state
+        isActive_: false
+    }
+
+    onConstructed() {
+        super.onConstructed();
+        console.log('MyCustomController constructed!');
+    }
+
+    afterSetIsActive(value, oldValue) {
+        console.log(`Controller active state changed from ${oldValue} to ${value}`);
+        // Perform actions based on active state change
+        if (value) {
+            this.doSomethingActive();
+        } else {
+            this.doSomethingInactive();
+        }
+    }
+
+    doSomethingActive() {
+        console.log('Controller is now active!');
+        // Example: enable a feature, start a timer
+    }
+
+    doSomethingInactive() {
+        console.log('Controller is now inactive!');
+        // Example: disable a feature, clear a timer
+    }
+}
+
+Neo.setupClass(MyCustomController);
+```
+
+## Conclusion
+
+The class extension mechanism, coupled with the reactive config system and `Neo.setupClass()`, forms the backbone of development in Neo.mjs. By mastering these principles, you can create highly modular, maintainable, and powerful applications that seamlessly integrate with the framework's core.