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

package/learn/guides/fundamentals/ExtendingNeoClasses.md

@@ -0,0 +1,359 @@
+
+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.
+
+
+
+## 4. Flexible Configuration of Instances: The `beforeSetInstance` Pattern
+
+Neo.mjs offers significant flexibility in how you configure properties that expect an instance of a Neo.mjs class
+(e.g., `store`, `layout`, `controller`). This flexibility is powered by the `Neo.util.ClassSystem.beforeSetInstance`
+utility, which intelligently converts various input types into the required instance.
+
+This pattern is commonly used within `beforeSet` lifecycle hooks to ensure that by the time a config property is set,
+it always holds a valid Neo.mjs instance.
+
+You can typically configure such properties using one of three methods:
+
+1.  **A Configuration Object (Plain JavaScript Object):**
+  Provide a plain JavaScript object with the desired properties. Neo.mjs will automatically create an instance of the
+  expected class (e.g., `Neo.data.Store` for the `store` config) using this object as its configuration. This is ideal
+  for inline, simple definitions.
+
+    ```javascript readonly
+    store: { // Neo.mjs will create a Store instance from this config
+        model: { fields: [{name: 'id'}, {name: 'name'}] },
+        data: [{id: 1, name: 'Item 1'}]
+    }
+    ```
+
+2.  **A Class Reference:**
+  Pass a direct reference to the Neo.mjs class. The framework will automatically instantiate this class when the
+  component is created.
+
+    ```javascript readonly
+    import MyCustomStore from './MyCustomStore.mjs';
+
+    // ...
+    store: MyCustomStore // Neo.mjs will create an instance of MyCustomStore
+    ```
+
+3.  **A Pre-created Instance:**
+    Provide an already instantiated Neo.mjs object (typically created using`Neo.create()`). This is useful when you need
+    to share a single instance across multiple components or manage its lifecycle externally.
+
+    ```javascript readonly
+    const mySharedStore = Neo.create(Neo.data.Store, { /* ... */ });
+
+    // ...
+    store: mySharedStore // Pass an already existing Store instance
+    ```
+
+This flexibility allows you to choose the most convenient and appropriate configuration style for your specific use case,
+from quick inline setups to robust, reusable class-based architectures.
+
+### Real-World Example: `Neo.grid.Container`'s `store` config
+
+A prime example of `beforeSetInstance` in action is the `store` config within `Neo.grid.Container`.
+The `beforeSetStore` hook ensures that the `store` property always holds a valid `Neo.data.Store` instance,
+regardless of how it was initially configured.
+
+```javascript readonly
+import ClassSystemUtil from '../../src/util/ClassSystem.mjs';
+import Store           from '../../src/data/Store.mjs';
+
+class GridContainer extends Neo.container.Base {
+    static config = {
+        className: 'Neo.grid.Container',
+        store_   : null // The reactive store config
+    }
+
+    /**
+     * Triggered before the store config gets changed.
+     * @param {Object|Neo.data.Store|null} value
+     * @param {Neo.data.Store}             oldValue
+     * @protected
+     */
+    beforeSetStore(value, oldValue) {
+        if (value) {
+            // This ensures that 'value' is always a Neo.data.Store instance.
+            // It handles plain objects (creating a new Store), class references,
+            // or pre-existing instances.
+            value = ClassSystemUtil.beforeSetInstance(value, Store);
+        }
+        return value;
+    }
+
+    // ... other methods
+}
+
+Neo.setupClass(GridContainer);
+```
+
+In this example, `ClassSystemUtil.beforeSetInstance(value, Store)` intelligently processes the `value`:
+*   If `value` is a plain JavaScript object, it creates a new `Neo.data.Store` instance using that object as its config.
+*   If `value` is a `Neo.data.Store` class reference, it instantiates that class.
+*   If `value` is already a `Neo.data.Store` instance, it returns it as is.
+
+This pattern is crucial for providing a flexible yet robust API for configuring complex properties.
+
+## 5. 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.

package/learn/guides/uibuildingblocks/CustomComponents.md

@@ -0,0 +1,287 @@
+## Introduction
+
+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.
+
+This guide will walk you through the process.
+
+## Choosing the Right Base Class
+
+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';
+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',
+
+        // 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);
+
+
+// 2. Use the new component in a view.
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype: 'vbox', align: 'start'},
+        items    : [{
+            // A standard framework button for comparison
+            module : Button,
+            iconCls: 'fa fa-home',
+            text   : 'A framework 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'}
+        }]
+    }
+}
+
+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).