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

package/learn/guides/ConfigSystemDeepDive.md

@@ -0,0 +1,280 @@
+
+**Pre-requisite:** It is highly recommended to study [The Unified Class Config System](#/learn/benefits.ConfigSystem)
+first to understand the foundational concepts and benefits.
+
+The Neo.mjs class configuration system is a cornerstone of the framework, providing a powerful, declarative, and
+reactive way to manage the state of your components and classes. Its internal mechanics are deeply intertwined with
+the instance lifecycle, ensuring predictable and consistent behavior. This guide will take you on a deep dive into
+how it achieves its remarkable consistency and power.
+
+## 1. Core Concepts Recap
+
+At its heart, the config system is built on a few key principles:
+
+*   **`static config` Block:** All configurable properties of a class are declared in a `static config = {}` block.
+    This provides a single, clear source of truth for a class's API.
+*   **`_` Suffix Convention:** Config properties that require custom logic when they change are declared with a trailing
+    underscore (e.g., `myValue_`). This signals the framework to automatically create a native getter and setter on the
+    class's prototype for this property.
+*   **Lifecycle Hooks:** For a config like `myValue_`, the framework provides optional lifecycle hooks that you can
+    implement in your class:
+    *   `beforeGetMyValue(value)`: Called before the getter returns the value.
+    *   `beforeSetMyValue(value, oldValue)`: Called before the setter applies the new value.
+    *   `afterSetMyValue(value, oldValue)`: Called after the setter has applied the new value.
+*   **Reactivity:** The `afterSet` hooks are the heart of the reactive system. They allow you to define logic that
+    automatically runs whenever a specific config property changes, ensuring your UI and application state are always
+    in sync.
+
+## 2. The Internal Mechanics: `set()`, `processConfigs()`, and `configSymbol`
+
+To truly understand how Neo.mjs handles complex scenarios like simultaneous updates and inter-dependencies, we must
+look at the internal machinery: the `set()` and `processConfigs()` methods in `Neo.core.Base`, and the special
+`configSymbol` object.
+
+### The `set()` Method: Your Gateway to Updates
+
+The `set()` method is the public interface for changing one or more config properties at once. When you call
+`this.set({a: 1, b: 2})`, you kick off a carefully orchestrated sequence.
+
+[[Source: core.Base.mjs](https://github.com/neomjs/neo/blob/dev/src/core/Base.mjs)]
+```javascript readonly
+// Simplified for clarity
+set(values={}) {
+    let me = this;
+
+    // If there are pending configs from a previous operation, process them first.
+    if (Object.keys(me[configSymbol]).length > 0) {
+        me.processConfigs();
+    }
+
+    // Stage the new values in the configSymbol object.
+    Object.assign(me[configSymbol], values); // (A)
+
+    // Start processing the newly staged values.
+    me.processConfigs(true); // (B)
+}
+```
+
+Here’s the breakdown:
+1.  **Pre-processing (within `construct()`):** The method first checks if the internal `configSymbol` object has any
+    leftover configs from a previous, unfinished operation (e.g., from a parent class's `construct()` call). If so,
+    it processes them to ensure a clean state before new values are staged.
+2.  **Staging (A):** `Object.assign(me[configSymbol], values)` is the critical first step. All new values from your
+    `set()` call are merged into the `configSymbol` object. This object acts as a **temporary staging area**. It
+    creates a snapshot of the intended end-state for all properties in this specific `set()` operation *before*
+    any individual setters or `afterSet` hooks are invoked.
+3.  **Processing (B):** `me.processConfigs(true)` is called. This kicks off the process of applying the staged values
+    from `configSymbol` to the actual instance properties. The `true` argument (`forceAssign`) is crucial, as we'll
+    see next.
+
+### The `processConfigs()` Method: The Heart of the Operation
+
+This internal method iteratively processes the configs stored in `configSymbol`. It's designed as a recursive
+function to handle the dynamic nature of config processing, where one `afterSet` might trigger another `set()`.
+
+[[Source: core.Base.mjs](https://github.com/neomjs/neo/blob/dev/src/core/Base.mjs)]
+```javascript readonly
+// Simplified for clarity
+processConfigs(forceAssign=false) {
+    let me   = this,
+        keys = Object.keys(me[configSymbol]); // Get keys of pending configs
+
+    if (keys.length > 0) {
+        let key = keys[0];
+        let value = me[configSymbol][key];
+
+        // The auto-generated setter for the config is triggered here.
+        me[key] = value; // (C)
+
+        // The config is removed from the staging area after its setter is called.
+        delete me[configSymbol][key]; // (D)
+
+        // Recursively call to process the next config.
+        me.processConfigs(forceAssign); // (E)
+    }
+}
+```
+
+*   **Iteration:** `processConfigs` takes the *first* key from `configSymbol`. It avoids a standard loop to prevent
+    issues if an `afterSet` hook modifies `configSymbol`.
+*   **Assignment (C):** `me[key] = value` is the most important step. This does **not** directly change a backing
+    field. Instead, it triggers the actual auto-generated **setter** for the config property (e.g., `set a(value)`).
+    This native setter is responsible for:
+    1.  Running the `beforeSet` hook (if it exists).
+    2.  Updating the internal backing property (e.g., `this._a = value`).
+    3.  Running the `afterSet` hook (if it exists and the value has changed).
+*   **Deletion (D):** `delete me[configSymbol][key]` removes the property from the staging area *after* its setter
+    has been invoked. This is vital to prevent reprocessing and to mark the config as handled.
+*   **Recursion (E):** The method calls itself to process the next item in `configSymbol` until it's empty.
+
+## 3. Solving the "Circular Reference" Problem
+
+What happens when two `afterSet` methods depend on each other's properties?
+
+Consider this common scenario:
+```javascript readonly
+class MyComponent extends Component {
+    static config = {
+        a_: 1,
+        b_: 2
+    }
+
+    afterSetA(value, oldValue) {
+        // This depends on 'b'
+        console.log(`a changed to ${value}, b is ${this.b}`);
+    }
+
+    afterSetB(value, oldValue) {
+        // This depends on 'a'
+        console.log(`b changed to ${value}, a is ${this.a}`);
+    }
+
+    onConstructed() {
+        super.onConstructed();
+        this.set({
+            a: 10,
+            b: 20
+        });
+    }
+}
+```
+When `this.set({a: 10, b: 20})` is called, which `afterSet` runs first? And when it runs, what value will it see
+for the *other* property?
+
+**This is where the brilliance of the `configSymbol` shines.**
+
+Here's the sequence:
+1.  **`set()` called:** `this.set({a: 10, b: 20})` is executed.
+2.  **Staging:** The `configSymbol` is immediately populated: `me[configSymbol] = {a: 10, b: 20}`. The internal
+    backing properties `_a` and `_b` have **not** been updated yet.
+3.  **`processConfigs()` starts:**
+    *   It picks `a`. The setter `setA(10)` is called.
+    *   Inside `setA`, the internal `this._a` is updated to `10`.
+    *   `afterSetA(10, 1)` is triggered.
+4.  **Inside `afterSetA`:**
+    *   The code encounters `this.b`. This calls the auto-generated getter for `b`.
+    *   **Crucially, the getter for `b` is smart.** It first checks if `b` exists as a key in the `configSymbol`
+        staging area.
+    *   It finds `b: 20` in `configSymbol` and immediately returns `20`, the **new, pending value**. It does *not*
+        return the old value from `this._b`.
+    *   The console logs: `a changed to 10, b is 20`.
+5.  **`processConfigs()` continues:**
+    *   `a` is removed from `configSymbol`.
+    *   The recursion continues, and it now picks `b`. The setter `setB(20)` is called.
+    *   Inside `setB`, `this._b` is updated to `20`.
+    *   `afterSetB(20, 2)` is triggered.
+6.  **Inside `afterSetB`:**
+    *   The code encounters `this.a`. The getter for `a` is called.
+    *   It checks `configSymbol`, but `a` is no longer there (it was processed).
+    *   It therefore returns the value from the internal backing property, `this._a`, which is now `10`.
+    *   The console logs: `b changed to 20, a is 10`.
+
+**Conclusion:** The `configSymbol` acts as a consistent, authoritative snapshot for the duration of a `set()`
+operation. This guarantees that all `afterSet` handlers, regardless of their execution order, operate on the most
+current and consistent state of all config properties involved in that operation.
+
+## 4. In-depth Example: A Reactive `MainContainer`
+
+Let's analyze a practical example to see these concepts in action. The `Neo.examples.core.config.MainContainer`
+demonstrates how to build a reactive UI declaratively.
+
+**The Goal:** Create a container with two labels. The text of each label is calculated based on the values of two
+config properties, `a` and `b`. A button allows the user to change `a` and `b` simultaneously.
+
+**The Declarative Approach (`static config`)**
+
+The entire UI structure, including child components and event handlers, is defined within the `static config` block.
+This is the recommended approach as it makes the component's structure immediately clear.
+
+```javascript readonly
+// From: Neo.examples.core.config.MainContainer
+import Panel    from '../../../src/container/Panel.mjs';
+import Viewport from '../../../src/container/Viewport.mjs';
+
+class MainContainer extends Viewport {
+    static config = {
+        className: 'Neo.examples.core.config.MainContainer',
+        a_: null,
+        b_: null,
+        style    : { padding: '20px' },
+        items: [{
+            module: Panel,
+            // ... panel configs
+            headers: [{
+                dock : 'top',
+                items: [
+                    { ntype: 'label', flag: 'label1' },
+                    { ntype: 'label', flag: 'label2' },
+                    { ntype: 'component', flex: 1 },
+                    {
+                        handler: 'up.changeConfig', // Declarative handler
+                        iconCls: 'fa fa-user',
+                        text   : 'Change configs'
+                    }
+                ]
+            }],
+            items: [{ ntype: 'label', text: 'Click the change configs button!' }]
+        }]
+    }
+
+    onConstructed() {
+        super.onConstructed();
+        this.set({ a: 5, b: 5 });
+    }
+
+    afterSetA(value, oldValue) {
+        if (oldValue !== undefined) {
+            this.down({flag: 'label1'}).text = value + this.b;
+        }
+    }
+
+    afterSetB(value, oldValue) {
+        if (oldValue !== undefined) {
+            this.down({flag: 'label2'}).text = value + this.a;
+        }
+    }
+
+    changeConfig(data) {
+        this.set({ a: 10, b: 10 });
+    }
+}
+```
+
+### Tracing the Data Flow
+
+1.  **Initialization (`onConstructed`)**:
+    *   `this.set({a: 5, b: 5})` is called. This happens within the `onConstructed()` lifecycle hook, which is guaranteed
+        to run *after* the instance's `construct()` method has fully processed its initial configuration.
+    *   `configSymbol` becomes `{a: 5, b: 5}`.
+    *   `afterSetA` runs. It calculates `label1.text` as `value (5) + this.b (reads 5 from configSymbol) = 10`.
+    *   `afterSetB` runs. It calculates `label2.text` as `value (5) + this.a (reads 5 from _a) = 10`.
+    *   **Initial State:** `label1` shows "10", `label2` shows "10".
+
+2.  **Button Click (`changeConfig`)**:
+    *   The button's `handler: 'up.changeConfig'` finds and calls the `changeConfig` method on the `MainContainer`.
+    *   `this.set({a: 10, b: 10})` is called.
+    *   `configSymbol` becomes `{a: 10, b: 10}`.
+    *   `afterSetA` runs. It calculates `label1.text` as `value (10) + this.b (reads 10 from configSymbol) = 20`.
+    *   `afterSetB` runs. It calculates `label2.text` as `value (10) + this.a (reads 10 from _a) = 20`.
+    *   **New State:** `label1` shows "20", `label2` shows "20".
+
+This example vividly demonstrates the dynamic and reactive nature of the system, where a single declarative state
+change automatically propagates through the component logic.
+
+## 5. Best Practices
+
+*   **Embrace Declarativity:** Define your entire UI structure inside `static config` whenever possible. This improves
+    readability and maintainability.
+*   **Use the `_` Suffix Wisely:** Only add the trailing underscore to configs that need `afterSet`, `beforeSet` or
+  `beforeGet` based logic. For simple value properties, omit it to avoid unnecessary overhead.
+*   **Keep `afterSet` Handlers Pure:** An `afterSet` handler should ideally only react to the change of its own
+    property and update other parts of the application. Avoid triggering complex chains of `set()` calls from within
+    an `afterSet` if possible.
+*   **Batch Updates with `set()`:** When you need to change multiple properties at once, always use a single
+    `set({a: 1, b: 2})` call. This is more efficient and ensures consistency, as demonstrated above.
+*   **Use `onConstructed` for Post-Construction Logic:** Use the `onConstructed` lifecycle method to perform any setup
+    that depends on the instance's initial configuration being fully processed. This is the ideal place for logic that
+    requires all configs to be set and potentially other instances to be created (if set-driven).
+
+By understanding these internal mechanics and following best practices, you can leverage the full power of Neo.mjs's
+class config system to build highly complex, reactive, and maintainable applications with confidence.

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).