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

package/learn/guides/InstanceLifecycle.md

@@ -1 +1,295 @@
-## todo
+Understanding the lifecycle of a class instance in Neo.mjs is crucial for building robust and predictable
+applications. The framework provides a series of well-defined hooks that allow you to tap into different stages of an
+instance's life, from its creation to its destruction.
+
+This guide will walk you through the entire lifecycle, starting with the initial synchronous steps and moving on to
+the asynchronous parts and destruction.
+
+## How the Lifecycle is Triggered
+
+While this guide details the lifecycle methods of an instance, it's important to understand how that lifecycle begins.
+In typical Neo.mjs application code, you will rarely call `Neo.create()` directly.
+
+The most common way to create component instances is declaratively, by defining configuration objects within a container's
+`items` array. The framework then internally uses `Neo.create()` to turn these configuration objects into fully-fledged
+instances, automatically initiating their lifecycle.
+
+It is crucial to **never** create a Neo.mjs class instance using the `new` keyword (e.g., `new MyComponent()`),
+as this would bypass the entire lifecycle initialization process described below, resulting in a broken and
+improperly configured instance. Always let the framework handle instantiation, either through declarative `items`
+configs or, in less common cases, by using `Neo.create()` directly.
+
+## 1. The Synchronous Creation Flow
+
+When the framework creates a new instance, it executes a sequence of synchronous methods. This initial phase is
+responsible for setting up the instance's basic configuration and state.
+
+The synchronous lifecycle methods are called in the following order:
+
+1.  **`new YourClass()`**: The framework first calls the actual JavaScript class constructor with **no arguments**.
+    This is a crucial step. Its primary purpose is to create the instance and initialize all of its defined class
+    fields. This ensures that by the time any Neo.mjs lifecycle method (like `construct`) or config hook
+    (like `beforeGetX`) is called, all class fields are fully available on `this`, preventing potential race
+    conditions or errors from accessing uninitialized properties.
+
+2.  **`construct(config)`**: This is the first Neo.mjs lifecycle hook called on the new instance. Its primary role is
+    to process the configuration object that was passed to `Neo.create()`. It's here that the initial values for
+    your configs are processed and applied via the config system.
+
+3.  **`onConstructed()`**: This hook is called immediately after `construct()` has finished. It's the ideal place to
+    perform any setup that depends on the initial configuration, such as setting initial values for other
+    properties or starting a process.
+
+4.  **`onAfterConstructed()`**: This hook is called after `onConstructed()`. It provides another opportunity for
+    setup logic, which can be useful for separating concerns or for logic that needs to run after the primary
+    `onConstructed` logic has completed.
+
+5.  **`init()`**: This is the final synchronous hook in the creation process. It's a general-purpose initialization
+    method that you can use for any final setup tasks before the instance is returned by `Neo.create()`.
+
+It's important to remember that all of these methods are synchronous. Any asynchronous operations should be handled
+in the later, asynchronous phases of the lifecycle.
+
+## 2. `constructor()` vs `construct()`: A Critical Distinction
+
+While you *can* define a standard JavaScript `constructor()` method on a Neo.mjs class, it is strongly discouraged
+and considered a bad practice. The framework provides the `construct()` lifecycle hook for a very specific and
+powerful reason: **pre-processing configs**.
+
+### The `constructor()` Limitation
+
+In standard JavaScript class inheritance, you **cannot** access the `this` context in a constructor before calling
+`super()`. This is a language-level restriction.
+
+```javascript
+// Anti-pattern: Do not do this in Neo.mjs
+constructor(config) {
+    // ERROR! 'this' is not available before super()
+    console.log(this.someClassField); 
+
+    super(config); // Assuming a parent constructor call
+}
+```
+
+### The `construct()` Advantage
+
+The `construct()` method, however, is just a regular method called by the framework *after* the instance has been
+fully created (via `new YourClass()`). This means that inside `construct()`, you have full access to `this` from the
+very first line.
+
+This enables a powerful pattern: you can inspect or modify the incoming `config` object *before* passing it up the
+inheritance chain with `super.construct(config)`. This is invaluable for component-specific logic.
+
+```javascript
+// The correct Neo.mjs pattern
+construct(config) {
+    // 'this' is fully available here!
+    // We can inspect the config and perform logic before the parent class does.
+    if (config.someFlag) {
+        config.title = 'Title set by child class';
+        this.someProperty = true;
+    }
+
+    // Now, pass the (potentially modified) config to the parent.
+    super.construct(config);
+}
+```
+
+In summary, always use `construct()` for your initialization logic. It provides the flexibility needed to work
+within the Neo.mjs lifecycle and config system, a flexibility that the standard `constructor()` cannot offer.
+
+## 3. The Asynchronous Initialization Flow
+
+After the synchronous creation methods are complete, the instance lifecycle moves into an asynchronous phase. This is
+where you should place any logic that cannot be executed synchronously, such as loading external files, fetching
+data from a server, or waiting for other resources to become available.
+
+This phase is orchestrated by a microtask scheduled from within the `construct()` method.
+
+### `initAsync()`: The Asynchronous Entry Point
+
+The core of this phase is the `async initAsync()` method.
+
+*   **Scheduling**: Immediately after the synchronous `construct()` logic is finished, the framework schedules a
+    microtask (`Promise.resolve().then(...)`) that will execute after the current JavaScript execution block is empty.
+*   **Execution**: This microtask calls and `await`s the `initAsync()` method. This is the designated place for all
+    asynchronous initialization logic. You can override this method in your own classes to perform tasks like
+    dynamic imports or initial data fetching.
+*   **Parent Call**: When overriding `initAsync()`, it is crucial to call `await super.initAsync()` at the beginning
+    of your implementation to ensure that parent classes can perform their own asynchronous setup, such as
+    registering remote methods.
+
+```javascript
+// In your class
+async initAsync() {
+    // Always call the parent method first!
+    await super.initAsync();
+
+    // Your async logic here
+    const myModule = await import('./MyOptionalModule.mjs');
+    this.data = await myService.fetchInitialData();
+}
+```
+
+### `isReady`: The Signal of Completion
+
+Once the `initAsync()` promise resolves, the framework sets the instance's `isReady` config to `true`.
+
+*   **`isReady_`**: The config is defined as `isReady_` (with a trailing underscore), which means it gets an
+    `afterSetIsReady(value, oldValue)` hook.
+*   **Reacting to Readiness**: You can implement the `afterSetIsReady()` method to be notified precisely when the
+    instance is fully initialized and ready for interaction. This is the most reliable way to coordinate logic that
+    depends on the component's full readiness.
+
+```javascript
+// In your class
+afterSetIsReady(isReady, wasReady) {
+    if (isReady && !wasReady) {
+        console.log('The instance is now fully ready!');
+        // Perform actions that require the component to be fully initialized
+    }
+}
+```
+
+This `initAsync` -> `isReady` pattern provides a robust and predictable way to manage the asynchronous parts of the
+instance lifecycle, ensuring that dependent logic only runs when the instance is in a known, ready state.
+
+## 4. Destruction: Cleaning Up with `destroy()`
+
+The final phase of the instance lifecycle is destruction. Properly cleaning up instances when they are no longer needed
+is critical for preventing memory leaks and ensuring your application remains performant over time. The `destroy()`
+method is the designated entry point for all cleanup logic.
+
+### The Base `destroy()` Implementation
+
+The `Neo.core.Base` class provides a foundational `destroy()` method that performs several key actions:
+
+*   **Clears Timeouts**: It clears any pending timeouts that were created using `this.timeout()`.
+*   **Unregisters Instance**: It unregisters the instance from the global `Neo.manager.Instance`, so it can no longer
+    be looked up by its ID.
+*   **Property Deletion**: It iterates over all properties of the instance and deletes them. This is an aggressive
+    strategy to help the JavaScript garbage collector reclaim memory by breaking references.
+*   **Single-Execution Guard**: The base class automatically intercepts the `destroy()` method to ensure that its core
+    logic can only be executed **once**, even if `destroy()` is called multiple times.
+
+### Overriding `destroy()`: Best Practices
+
+When your class holds references to other Neo.mjs instances or external resources, you must override the `destroy()`
+method to manage them correctly. The primary goal is to break all circular references and remove any listeners or
+registrations so that the instance can be safely garbage collected.
+
+Here is an example from `Neo.grid.Container` that illustrates key best practices:
+
+```javascript
+// Example from src/grid/Container.mjs
+destroy(...args) {
+    let me = this;
+
+    // 1. Clean up SHARED instances (e.g., Stores)
+    // We don't destroy the store, as it might be used by other components.
+    // Setting it to null will trigger the afterSetStore hook, which is the
+    // correct place to remove any listeners this grid added to the store.
+    me.store = null;
+
+    // 2. Destroy OWNED instances
+    // The grid container creates and owns its scrollManager, so it's
+    // responsible for destroying it.
+    me.scrollManager.destroy();
+
+    // 3. Unregister from external services/managers
+    // The component had previously registered with the ResizeObserver addon.
+    // It must unregister to prevent the addon from holding a dead reference.
+    me.mounted && Neo.main.addon.ResizeObserver.unregister({
+        id      : me.id,
+        windowId: me.windowId
+    });
+
+    // 4. ALWAYS call super.destroy() LAST
+    // This executes the base cleanup logic after your custom logic is complete.
+    super.destroy(...args);
+}
+```
+
+To summarize the best practices:
+
+1.  **Call `super.destroy()` Last**: Always end your `destroy()` method with `super.destroy(...args)`. If you call it
+    first, `this` will be partially dismantled, and subsequent calls on it will likely fail.
+2.  **Destroy Owned Instances**: If your class creates its own instances of other Neo.mjs classes (e.g., helpers,
+    managers), you are responsible for calling `destroy()` on them.
+3.  **Clean Up Shared Instances**: If your class uses a shared instance (like a `Store` or a global service), do **not**
+    call `destroy()` on it. Instead, remove any listeners you added to it. A good pattern is to set the config
+    property to `null` (e.g., `this.store = null`) and perform the listener cleanup inside the `afterSet` hook.
+4.  **Unregister from Services**: If your class registered itself with any external manager or service (like the
+    `ResizeObserver`), be sure to unregister from it.
+
+## 5. Lifecycle of Nested Instances: Set-Driven vs. Get-Driven
+
+A powerful feature of the config system is that a config property can be another Neo.mjs class instance. A common
+example is a grid's `selectionModel`. This raises an important architectural question: when should this nested
+instance be created? The framework supports two patterns, each with different implications for the lifecycle.
+
+### The Set-Driven Approach (Eager Instantiation)
+
+In this pattern, you ensure the instance is created as soon as the config is set. This is typically done inside a
+`beforeSet` hook.
+
+The `Neo.grid.Body` class provides a perfect example with its `selectionModel_` config.
+
+```javascript
+// In Neo.grid.Body
+beforeSetSelectionModel(value, oldValue) {
+    oldValue?.destroy();
+
+    // beforeSetInstance ensures the value is a valid instance,
+    // creating one from a config object if necessary.
+    return ClassSystemUtil.beforeSetInstance(value, RowModel);
+}
+```
+
+When the framework processes the grid body's configs during its `construct` phase, `beforeSetSelectionModel` is
+called. It immediately creates the selection model instance.
+
+**The key takeaway is the guarantee this provides for `onConstructed()`**. Because the selection model was
+instantiated during `construct`, by the time `onConstructed()` is called, you can safely assume the instance exists.
+
+```javascript
+// In Neo.grid.Body
+onConstructed() {
+    super.onConstructed();
+
+    // This is safe because beforeSetSelectionModel already created the instance.
+    this.selectionModel?.register(this);
+}
+```
+
+Use the set-driven approach when a nested instance is **essential** for the component's core functionality and needs
+to be available immediately after construction.
+
+### The Get-Driven Approach (Lazy Instantiation)
+
+Alternatively, you can defer the creation of a nested instance until it's actually needed for the first time. This
+is achieved by creating the instance within a `beforeGet` hook. This "lazy" approach can improve initial creation
+performance if the nested instance is complex or not always used.
+
+`Neo.grid.Body` also demonstrates this pattern with its `columnPositions_` config.
+
+```javascript
+// In Neo.grid.Body
+beforeGetColumnPositions(value) {
+    // If the backing field (_columnPositions) is null...
+    if (!value) {
+        // ...create the instance now.
+        this._columnPositions = value = Neo.create({
+            module     : Collection,
+            keyProperty: 'dataField'
+        });
+    }
+    return value;
+}
+```
+
+With this pattern, the `columnPositions` collection is **not** created during the `construct` phase. It is only
+instantiated the very first time some other code calls `this.columnPositions`.
+
+Use the get-driven approach for non-essential or heavy nested instances to optimize performance and memory usage,
+especially if they are only used in specific scenarios.

package/learn/guides/Layouts.md

@@ -1 +1,246 @@
-## todo
+## Understanding Layouts in Neo.mjs
+
+Layouts are fundamental to arranging components within your application's user interface. In Neo.mjs, layouts are
+managed declaratively through the `layout` configuration property of container components. This system provides a
+powerful and flexible way to control the positioning, sizing, and alignment of child components.
+
+### How Layouts Work
+
+Every container component (any class extending `Neo.container.Base`) can have a `layout` config. This config defines
+how the container's `items` (its child components) are arranged. When you set a `layout` on a container, the framework
+automatically handles the positioning and sizing of its children, adapting to different screen sizes and dynamic content.
+
+### The `layout` Config
+
+The `layout` config is an object that typically includes an `ntype` property, specifying the type of layout to use.
+Depending on the `ntype`, additional properties can be provided to customize the layout's behavior.
+
+Example:
+
+```javascript
+layout: {
+    ntype: 'vbox',
+    align: 'center'
+}
+```
+
+### The 'base' Layout (`ntype: 'base'`)
+
+In scenarios where you prefer to manage the positioning and sizing of child components entirely through custom CSS or
+in-line styles, you can use the `'base'` layout. This layout type provides minimal interference, essentially acting as a
+pass-through, allowing you full control over the styling of your container's children.
+
+When `ntype: 'base'` is used, the container will not apply any specific flexbox or grid-based layout rules to its children.
+This is useful for highly customized components or when integrating with external styling libraries.
+
+### Common Layout Types
+
+Neo.mjs provides several built-in layout types to cover a wide range of UI design needs. Here, we'll explore some of the
+most commonly used ones.
+
+#### 1. VBox Layout (`ntype: 'vbox'`)
+
+The VBox (Vertical Box) layout arranges child components in a single vertical column. It's ideal for creating stacked
+sections or forms where elements flow from top to bottom.
+
+**Key Properties for VBox Layouts:**
+
+-   `align`: Controls the horizontal alignment of items within the column.
+    -   `'left'` (default): Aligns items to the left.
+    -   `'center'`: Centers items horizontally.
+    -   `'right'`: Aligns items to the right.
+    -   `'stretch'`: Stretches items to fill the available width of the container.
+
+-   `pack`: Controls how items are packed along the vertical axis (main axis).
+    -   `'start'` (default): Items are packed towards the top.
+    -   `'center'`: Items are centered vertically.
+    -   `'end'`: Items are packed towards the bottom.
+    -   `'space-between'`: Items are evenly distributed with space between them.
+    -   `'space-around'`: Items are evenly distributed with space around them (including half-space at ends).
+
+-   `flex`: A property applied to individual child items, not the layout itself. It determines how an item grows or
+    shrinks to fill available space within the VBox. A `flex` value of `1` means the item will expand to fill remaining
+    space.
+
+**Example:**
+
+```javascript live-preview
+import Container from '../container/Base.mjs';
+import Button from '../button/Base.mjs';
+
+class VBoxExample extends Container {
+    static config = {
+        className: 'Example.view.VBoxExample',
+        layout: {
+            ntype: 'vbox',
+            align: 'center', // Center items horizontally
+            pack: 'center'   // Center items vertically
+        },
+        items: [{
+            module: Button,
+            text: 'Button 1',
+            width: 100
+        }, {
+            module: Button,
+            text: 'Button 2',
+            width: 150
+        }, {
+            module: Button,
+            text: 'Button 3',
+            flex: 1 // This button will expand to fill remaining vertical space
+        }]
+    }
+}
+
+Neo.setupClass(VBoxExample);
+```
+
+#### 2. HBox Layout (`ntype: 'hbox'`)
+
+The HBox (Horizontal Box) layout arranges child components in a single horizontal row. It's commonly used for toolbars,
+navigation menus, or any scenario where elements need to be displayed side-by-side.
+
+**Key Properties for HBox Layouts:**
+
+-   `align`: Controls the vertical alignment of items within the row.
+    -   `'top'` (default): Aligns items to the top.
+    -   `'center'`: Centers items vertically.
+    -   `'bottom'`: Aligns items to the bottom.
+    -   `'stretch'`: Stretches items to fill the available height of the container.
+
+-   `pack`: Controls how items are packed along the horizontal axis (main axis).
+    -   `'start'` (default): Items are packed towards the left.
+    -   `'center'`: Items are centered horizontally.
+    -   `'end'`: Items are packed towards the right.
+    -   `'space-between'`: Items are evenly distributed with space between them.
+    -   `'space-around'`: Items are evenly distributed with space around them (including half-space at ends).
+
+-   `flex`: Similar to VBox, `flex` applied to individual child items determines how they grow or shrink to fill
+    available horizontal space within the HBox.
+
+**Example:**
+
+```javascript live-preview
+import Container from '../container/Base.mjs';
+import Button from '../button/Base.mjs';
+
+class HBoxExample extends Container {
+    static config = {
+        className: 'Example.view.HBoxExample',
+        layout: {
+            ntype: 'hbox',
+            align: 'center', // Center items vertically
+            pack: 'start'    // Pack items to the left
+        },
+        items: [{
+            module: Button,
+            text: 'Button A',
+            height: 50
+        }, {
+            module: Button,
+            text: 'Button B',
+            height: 70
+        }, {
+            module: Button,
+            text: 'Button C',
+            flex: 1 // This button will expand to fill remaining horizontal space
+        }]
+    }
+}
+
+Neo.setupClass(HBoxExample);
+```
+
+#### 3. Card Layout (`ntype: 'card'`)
+
+The Card layout is designed to display one child component at a time, making it ideal for tab panels, wizards, or any
+interface where content needs to be switched without navigating away. Only the active card is visible, while others are
+hidden.
+
+**Key Properties for Card Layouts:**
+
+-   `activeIndex_`: This is the most important config. Changing its value activates a different child component (card).
+    The framework automatically handles showing the new card and hiding the old one.
+
+-   `removeInactiveCards`: A boolean (default `true`). If `true`, the DOM elements of inactive cards are removed from the
+    document flow, keeping only their instances and VDOM trees. This is useful for performance, especially with many
+    cards, as it reduces the number of elements the browser has to render. If `false`, inactive cards remain in the DOM
+    but are hidden via CSS.
+
+-   `slideDirection_`: A string (`'horizontal'`, `'vertical'`, or `null` - default `null`). This property enables
+    animated transitions when switching between cards. Setting it to `'horizontal'` or `'vertical'` will make the cards
+    slide into view.
+
+**Example:**
+
+```javascript live-preview
+import Container from '../container/Base.mjs';
+import Button from '../button/Base.mjs';
+
+class CardExample extends Container {
+    static config = {
+        className: 'Example.view.CardExample',
+        layout: {
+            ntype: 'card',
+            activeIndex: 0 // Start with the first card active
+        },
+        items: [{
+            module: Container,
+            cls: 'card-panel',
+            items: [{
+                module: Button,
+                text: 'Go to Card 2',
+                handler: function() {
+                    this.up('container').layout.activeIndex = 1;
+                }
+            }],
+            style: {
+                backgroundColor: '#e0f7fa',
+                padding: '20px',
+                textAlign: 'center'
+            }
+        }, {
+            module: Container,
+            cls: 'card-panel',
+            items: [{
+                module: Button,
+                text: 'Go to Card 1',
+                handler: function() {
+                    this.up('container').layout.activeIndex = 0;
+                }
+            }],
+            style: {
+                backgroundColor: '#fff3e0',
+                padding: '20px',
+                textAlign: 'center'
+            }
+        }]
+    }
+}
+
+Neo.setupClass(CardExample);
+```
+
+#### Lazy Loading with Card Layouts
+
+One powerful feature of the Card layout is its ability to lazy load content. This means that the JavaScript module for a
+card's content is only loaded when that card becomes active, significantly improving initial application load times.
+
+This is achieved by defining the `module` property of an item within the `items` array as a function that returns a
+dynamic `import()` statement. For example, in the Portal app's `Viewport.mjs`,
+modules are lazy-loaded like this:
+
+```javascript
+items: [
+    {module: () => import('./home/MainContainer.mjs')},
+    {module: () => import('./learn/MainContainer.mjs')},
+    // ... other lazy-loaded modules
+]
+```
+
+When `activeIndex` changes to a card configured this way, Neo.mjs automatically executes the import function, loads the
+module, and then creates the component instance. This ensures that resources are only consumed when they are actually
+needed.
+
+This is just the beginning of understanding layouts in Neo.mjs. In subsequent sections, we will explore more advanced
+layout types and concepts like nesting layouts for complex UI structures.