Refactor defineComponent and Enhance Config System Documentation #7019

Author: tobiu

src/Neo.mjs

@@ -496,11 +496,33 @@ Neo = globalThis.Neo = Object.assign({
      */
 
     /**
-     * Internally used at the end of each class / module definition
+     * This is the final and most critical step in the Neo.mjs class creation process.
+     * It is called at the end of every class module definition.
+     *
+     * `setupClass` performs several key operations:
+     * 1.  **Configuration Merging:** It traverses the prototype chain to merge `static config`
+     *     objects from parent classes into the current class, creating a unified `config`.
+     * 2.  **Applying Overwrites:** It calls the static `applyOverwrites()` method on the class,
+     *     allowing the global `Neo.overwrites` object to modify the class's default prototype
+     *     configs. This is a key mechanism for external theming and configuration.
+     * 3.  **Reactive Getter/Setter Generation:** For any config ending with an underscore (e.g., `myConfig_`),
+     *     it automatically generates the corresponding public getter and setter. This enables optional
+     *     lifecycle hooks that are called automatically if implemented on the class:
+     *     - `beforeGetMyConfig(value)`
+     *     - `beforeSetMyConfig(newValue, oldValue)`
+     *     - `afterSetMyConfig(newValue, oldValue)`
+     * 4.  **Prototype-based Configs:** Non-reactive configs (without an underscore) are set
+     *     directly on the prototype for memory efficiency.
+     * 5.  **Mixin Application:** It processes the `mixins` config to blend in functionality from
+     *     other classes.
+     * 6.  **Namespace Registration:** It registers the class in the global `Neo` namespace.
+     * 7.  **Singleton Instantiation:** If the class is configured as a singleton, it creates the
+     *     single instance.
+     *
      * @memberOf module:Neo
      * @template T
-     * @param {T} cls
-     * @returns {T}
+     * @param {T} cls The class constructor to process.
+     * @returns {T} The processed and finalized class constructor or singleton instance.
      */
     setupClass(cls) {
         let baseConfig            = null,

src/core/Base.mjs

@@ -58,7 +58,26 @@ class Base {
      */
     static overwrittenMethods = {}
     /**
-     * Configs will get merged throughout the class hierarchy
+     * Defines the default configuration properties for the class. These configurations are
+     * merged throughout the class hierarchy and can be overridden at the instance level.
+     *
+     * There are two main types of configs:
+     *
+     * 1.  **Reactive Configs:** Property names ending with a trailing underscore (e.g., `myConfig_`).
+     *     The framework automatically generates a public getter and setter, removing the underscore
+     *     from the property name (e.g., `this.myConfig`). This system enables powerful, optional
+     *     lifecycle hooks that are called automatically if they are implemented on the class:
+     *     - `beforeGetMyConfig(value)`: Executed before the getter returns. Can be used to dynamically modify the returned value.
+     *     - `beforeSetMyConfig(newValue, oldValue)`: Executed before a new value is set. Can be used for validation or transformation. Returning `undefined` from this hook will cancel the update.
+     *     - `afterSetMyConfig(newValue, oldValue)`: Executed after a new value has been successfully set. Ideal for triggering side effects.
+     *
+     * 2.  **Non-Reactive (Prototype-based) Configs:** Property names without a trailing underscore.
+     *     These are applied directly to the class's **prototype** during the `Neo.setupClass`
+     *     process. This is highly memory-efficient as the value is shared across all instances.
+     *     It also allows for powerful, application-wide modifications of default behaviors
+     *     by using the `Neo.overwrites` mechanism, which modifies these prototype values at
+     *     load time.
+     *
      * @returns {Object} config
      */
     static config = {
@@ -290,9 +309,38 @@ class Base {
     }
 
     /**
-     * Applying overwrites and adding overwrittenMethods to the class constructors
-     * @param {Object} cfg
+     * This static method is called by `Neo.setupClass()` during the class creation process.
+     * It allows for modifying a class's default prototype-based configs from outside the
+     * class hierarchy, which is a powerful way to avoid boilerplate code.
+     *
+     * It looks for a matching entry in the global `Neo.overwrites` object based on the
+     * class's `className`. If found, it merges the properties from the overwrite object
+     * into the class's static `config`. This provides a powerful mechanism for theming
+     * or applying application-wide customizations to framework or library classes without
+     * needing to extend them.
+     *
+     * @example
+     * // Imagine you have hundreds of buttons in your app, and you want all of them
+     * // to have `labelPosition: 'top'` instead of the default `'left'`. 
+     * // Instead of configuring each instance, you can define an overwrite.
+     * 
+     * // inside an Overwrites.mjs file loaded by your app:
+     * Neo.overwrites = {
+     *     Neo: {
+     *         button: {
+     *             Base: {
+     *                 labelPosition: 'top'
+     *             }
+     *         }
+     *     }
+     * };
+     * 
+     * // Now, every `Neo.button.Base` (and any class that extends it) will have this
+     * // new default value on its prototype.
+     *
+     * @param {Object} cfg The static `config` object of the class being processed.
      * @protected
+     * @static
      */
     static applyOverwrites(cfg) {
         let overwrites = Neo.ns(cfg.className, false, Neo.overwrites),

src/functional/defineComponent.mjs

@@ -13,9 +13,10 @@ import FunctionalBase from './component/Base.mjs';
  * import { useConfig }       from 'neo/functional/useConfig.mjs';
  *
  * const MyComponent = defineComponent({
- *     // 1. Static properties are defined first for a clear mental model.
- *     // This object is directly used as the class's `static config`.
- *     static: {
+ *     // 1. The `config` object directly defines the class's `static config`.
+ *     // This is where you set the className, ntype, and all default values
+ *     // for your component's reactive (e.g., `text_`) and non-reactive (e.g., `className`) configs.
+ *     config: {
  *         className: 'MyApp.MyFunctionalComponent',
  *         ntype    : 'my-functional-component',
  *
@@ -24,7 +25,7 @@ import FunctionalBase from './component/Base.mjs';
  *         text_: 'Hello World'
  *     },
  *
- *     // 2. Methods (instance logic) follow the static definition.
+ *     // 2. Methods (instance logic) follow the config definition.
  *     createVdom(config) {
  *         const [count, setCount] = useConfig(0);
  *
@@ -59,16 +60,16 @@ import FunctionalBase from './component/Base.mjs';
  * // });
  */
 export function defineComponent(spec) {
-    const staticSpec = spec.static;
-    delete spec.static;
+    const configSpec = spec.config;
+    delete spec.config;
 
-    if (!staticSpec?.className) {
-        throw new Error('defineComponent requires a static config with a className.');
+    if (!configSpec?.className) {
+        throw new Error('defineComponent requires a config object with a className.');
     }
 
     class FunctionalComponent extends FunctionalBase {
         static config = {
-            ...staticSpec
+            ...configSpec
             // We can add our own configurations here
         }
     }