working on documentation

Author: levizwannah

docs/components.md

@@ -43,6 +43,12 @@ ojs(MyComponent);
 4.  **`ojs(MyComponent)`**: Registers the component with the framework.
 5.  **Passing Arguments**: The `render` method receives `...args` which can contain parent elements, attributes, or other data passed during rendering. Always spread `...args` in your root element or handle them appropriately.
 
+> [!IMPORTANT]
+> **Registration is Required Before Use**
+> You **MUST** call `ojs(YourComponent)` to register the component in the IoC container. This **MUST** happen before you try to use the component (e.g., `h.YourComponent()`).
+>
+> The most common pattern is to call `ojs(YourComponent)` at the very end of your component file, ensuring it is registered as soon as the file is imported.
+
 ## Functional Components
 
 Functional components are simpler and are best used for presentational components that don't require complex state management or lifecycle hooks.

docs/container.md

@@ -0,0 +1,117 @@
+# IoC Container & `app()` Service
+
+OpenScript uses an **Inversion of Control (IoC) Container** to manage dependencies and global services. This promotes loose coupling and makes your application easier to test and maintain.
+
+## The `app()` Helper
+
+The most common way to interact with the container is via the `app()` helper function.
+
+### Accessing Services
+
+You can retrieve any registered service by passing its name to `app()`.
+
+```javascript
+import { app } from "modular-openscriptjs";
+
+// Get the Router instance
+const router = app("router");
+
+// Get the Broker
+const broker = app("broker");
+
+// Get a context (if registered)
+const globalContext = app("gc");
+```
+
+### Accessing the Container
+
+Calling `app()` without arguments returns the **Container** instance itself. This is useful when you need to register new services or values.
+
+```javascript
+const container = app();
+
+// Register a new value
+container.value("myConfig", { apiKey: "12345" });
+```
+
+## Registering Services
+
+You typically register services in your `ojs.config.js` or a setup file.
+
+### `container.value(name, value)`
+
+Registers a constant value or an existing instance. This is the most common method for configuration or pre-instantiated classes.
+
+```javascript
+import { app } from "modular-openscriptjs";
+import { appEvents } from "./events.js";
+
+// Registering appEvents so it can be resolved anywhere
+app().value("appEvents", appEvents);
+```
+
+### `container.singleton(name, Class, dependencies)`
+
+Registers a class as a singleton. The container will create **one** instance the first time it is resolved and return that same instance forever.
+
+```javascript
+// Register API Service
+app().singleton("api", ApiService);
+
+// Later...
+const api = app("api"); // Creates instance
+const api2 = app("api"); // Returns same instance
+```
+
+### `container.transient(name, Class, dependencies)`
+
+Registers a class as transient. The container will create a **new** instance every time it is resolved.
+
+```javascript
+app().transient("logger", Logger);
+```
+
+### `container.factory(name, factoryFunction)`
+
+Registers a factory function. The function is called to produce the value.
+
+```javascript
+app().factory("timestamp", () => Date.now());
+```
+
+## Resolving Services
+
+While `app('name')` is the shortcut, you can also use `container.resolve('name')`.
+
+```javascript
+const myService = app().resolve("myService", "defaultValue");
+```
+
+### Dependency Injection
+
+When defining services that depend on others, you can pass an array of dependency names.
+
+```javascript
+class UserService {
+  constructor(api, broker) {
+    this.api = api;
+    this.broker = broker;
+  }
+}
+
+// Register UserService with dependencies 'api' and 'broker'
+app().singleton("userService", UserService, ["api", "broker"]);
+
+// When resolving, container auto-injects "api" and "broker"
+const userService = app("userService");
+```
+
+## Core Services
+
+The following services are registered by default:
+
+- `"h"`: The Markup Engine (Proxy)
+- `"router"`: The Router instance
+- `"broker"`: The Event Broker
+- `"repository"`: Internal Component Repository
+- `"contextProvider"`: The Context Provider

docs/helpers.md

@@ -0,0 +1,134 @@
+# Helper Functions
+
+OpenScript provides a set of global helper functions and utilities to simplify common tasks, DOM manipulation, and framework interaction.
+
+## Logic Helpers
+
+These helpers are available globally (e.g., `window.ifElse`) and can be used directly in your code or templates.
+
+### `ifElse(condition, trueValue, falseValue)`
+
+Evaluates a condition and returns one of two values. If the values are functions, they are executed.
+
+```javascript
+// Basic usage
+const status = ifElse(isOnline, "Online", "Offline");
+
+// With functions (lazy evaluation)
+const result = ifElse(
+  isValid,
+  () => complexCalculation(),
+  () => "Invalid",
+);
+```
+
+### `coalesce(value1, value2)`
+
+Returns the first non-null/undefined value. Handy for defaults.
+
+```javascript
+const name = coalesce(userInput, "Guest");
+```
+
+### `each(iterable, callback)`
+
+Safely iterates over arrays or objects. Returns an array of results.
+
+```javascript
+// Array
+each([1, 2, 3], (num) => console.log(num));
+
+// Object
+each({ a: 1, b: 2 }, (val, key) => console.log(key, val));
+```
+
+### `lazyFor(array, callback)`
+
+Iterates over an array asynchronously using `setTimeout(..., 0)` to avoid blocking the main thread during large operations.
+
+```javascript
+lazyFor(hugeArray, (item) => {
+  // Process item without freezing UI
+});
+```
+
+---
+
+## DOM Utilities (`dom`)
+
+The `dom` object provides shortcuts for common DOM operations.
+
+### Selection
+
+- **`dom.id(id)`**: wrapper for `document.getElementById`.
+- **`dom.get(selector, parent?)`**: wrapper for `querySelector`.
+- **`dom.all(selector, parent?)`**: wrapper for `querySelectorAll`.
+- **`dom.byClass(className, parent?)`**: wrapper for `getElementsByClassName`.
+
+### Manipulation
+
+- **`dom.create(type)`**: wrapper for `document.createElement`.
+- **`dom.put(html, element, append = false)`**: Sets `innerHTML`.
+- **`dom.clear(element)`**: Clears `innerHTML`.
+- **`dom.disable(element)` / `dom.enable(element)`**: Toggles `disabled` attribute.
+
+### Positioning
+
+- **`dom.centerInside(container, element)`**: Centers an absolutely positioned element within a container.
+
+---
+
+## Framework Helpers
+
+### `app(serviceName?)`
+
+Access the IoC Container.
+
+- `app("router")`: Get Router.
+- `app("broker")`: Get Event Broker.
+- `app()`: Get the Container instance itself.
+
+### `component(id)`
+
+Retrieves a Component instance by its unique ID (UID).
+Useful in event listeners where you have the UID but not the instance.
+
+```javascript
+const myComp = component(123);
+myComp?.setState(newState);
+```
+
+### `context(name)` & `putContext(name, value)`
+
+Shortcuts for the Context API.
+
+- `context("theme")`: Get the "theme" context.
+- `putContext("theme", "dark")`: Define/Update the "theme" context.
+
+### `state(initialValue)`
+
+Creates a new State object.
+
+```javascript
+const count = state(0);
+```
+
+### `v(state, callback)`
+
+Creates an "Anonymous Component" that updates when the bound state changes.
+
+```javascript
+// Renders text that updates automatically
+h.div(
+  {},
+  v(countState, (val) => `Count is: ${val}`),
+);
+```
+
+### `ojs(...classes)`
+
+The main entry point to run the application runner.
+
+```javascript
+ojs(AppClass);
+```

docs/mediators.md

@@ -7,14 +7,38 @@ Mediators act as the bridge between your application's logic (backend/services)
 Mediators are **stateless** classes that listen for events, execute logic (like API calls or data processing), and then potentially emit new events. They do not manipulate the DOM directly.
 
 ```javascript
-// Example Mediator structure
+// AuthMediator.js
 export default class AuthMediator extends Mediator {
   shouldRegister() {
-    return true; // Control registration logic
+    return true;
   }
 }
 ```
 
+### Best Practice: `boot.js`
+
+For Mediators, it is best practice to have a dedicated `boot.js` (or `mediators.js`) file that imports and registers them all. This ensures they are registered early in the application lifecycle.
+
+```javascript
+// src/boot.js
+import { ojs } from "modular-openscriptjs";
+import AuthMediator from "./mediators/AuthMediator";
+import CartMediator from "./mediators/CartMediator";
+
+export default function boot() {
+  ojs(AuthMediator, CartMediator);
+}
+```
+
+Then, in your `main.js`:
+
+```javascript
+// src/main.js
+import boot from "./boot";
+
+boot(); // Registers all mediators
+```
+
 ## Broker Registration
 
 When you define a Mediator, it is automatically registered with the **Broker** if `shouldRegister()` returns `true`. The broker scans the mediator for special properties to set up event listeners.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "modular-openscriptjs",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "description": "OpenScriptJs Framework - A lightweight, reactive JavaScript framework for building modern web applications",
   "type": "module",
   "main": "./dist/modular-openscriptjs.umd.js",

src/utils/helpers.js

@@ -23,7 +23,6 @@ export function namespace(name) {
 
 export function cleanUpNode(node) {
   node.__openscript_cleanup__?.();
-  node.__eventListeners = null;
 }
 
 /**