added callback to handle cleanups

Author: levizwannah

build/vite-plugin-openscript.js

@@ -203,8 +203,15 @@ export function openScriptComponentPlugin(options = {}) {
       if (hasChanged) {
         // Check if Component is imported
         // Matches: import { Component } ... or import ... Component ...
+        // We use a regex that supports multi-line named imports by looking inside braces
+
+        const hasNamedImport =
+          /import\s*\{[^}]*?\bComponent\b[^}]*?\}\s*from/.test(code);
+        const hasDefaultOrNamespaceImport =
+          /import\s+(?:[\w*\s,]*\bComponent\b)/.test(code);
+
         // Simple check:
-        if (!code.includes("import") || !code.match(/import\s+.*Component/)) {
+        if (!hasNamedImport && !hasDefaultOrNamespaceImport) {
           // Need to import Component.
           // Check if existing import from "modular-openscriptjs" exists
           if (code.includes("modular-openscriptjs")) {

docs/components.md

@@ -78,12 +78,18 @@ OpenScript provides a declarative way to listen to events on elements.
 
 When creating an element with `h`, you can pass a `listeners` object in the attributes.
 
+> [!TIP]
+> It is recommended to use **anonymous functions** for listeners to avoid potential memory leaks associated with direct binding. While OpenScript is generally memory-safe, using anonymous functions ensures that references are properly managed and collected.
+
 ```javascript
 h.button(
   {
     class: "btn",
     listeners: {
-      click: this.handleClick.bind(this),
+      // Preferred: Anonymous function
+      click: (e) => this.handleClick(e),
+
+      // Also safe: Arrow functions defined inline
       mouseover: (e) => console.log("Hovered", e),
     },
   },
@@ -93,7 +99,7 @@ h.button(
 
 ### Method Binding
 
-For class components, it's common to define methods for event handlers. Remember to `.bind(this)` or use arrow functions to preserve the correct `this` context.
+While you can bind methods directly, be aware that creating new bound functions (e.g., `.bind(this)`) on every render can potentially lead to memory overhead if not handled correctly by the garbage collector.
 
 ```javascript
 export default class Counter extends Component {
@@ -107,7 +113,8 @@ export default class Counter extends Component {
     return h.button(
       {
         listeners: {
-          click: this.increment.bind(this), // Binding is crucial
+          // Anonymous function wrapper is preferred over .bind(this)
+          click: () => this.increment(),
         },
       },
       "+",
@@ -118,7 +125,59 @@ export default class Counter extends Component {
 
 ### Special Event Methods
 
-If your component class defines methods starting with `$_`, OpenScript automatically treats them as event listeners for the component instance itself (lifecycle events).
+OpenScript provides conventions for automatically listening to events based on method names.
+
+#### Component Lifecycle & Emitted Events (`$_`)
+
+Methods starting with `$_` are treated as listeners for events emitted by the component itself (including lifecycle events).
 
 - `$_mounted()`: Called when the component is added to the DOM.
 - `$_rendered()`: Called when the component is rendered.
+- `$_customEvent()`: Listens for `this.emit('customEvent')`.
+
+#### Broker Events (`$$`)
+
+Methods starting with `$$` are treated as listeners for global events emitted via the **Broker**.
+
+- `$$app_started()`: Listens for `app:started` event (dots/colons usually mapped to underscores).
+- `$$user_login()`: Listens for `user:login` event.
+
+```javascript
+export default class UserProfile extends Component {
+  // Listen to component's own mount event
+  $_mounted() {
+    console.log("UserProfile mounted");
+  }
+
+  // Listen to global 'auth:logout' event from Broker
+  $$auth_logout(user) {
+    console.log("User logged out:", user);
+    this.cleanUp();
+  }
+}
+```
+
+### Inline Attribute Listeners
+
+For inline event attributes (like `onclick`, `onchange`, etc.) that mimic standard HTML attributes, you can use `this.method('methodName', ...args)`. This approach allows you to reference component methods directly in the string attribute, which is useful when standard `listeners` object binding isn't applicable or preferred for specific attribute-based APIs.
+
+```javascript
+export default class MyComponent extends Component {
+  greet(name) {
+    alert(`Hello, ${name}!`);
+  }
+
+  render() {
+    // Uses this.method to create a reference to the 'greet' method
+    // 'onclick' here is treated as an attribute, not a direct event listener attachment
+    return h.button(
+      {
+        onclick: this.method("greet", "Levi"), // effectively onclick="...greet('Levi')"
+      },
+      "Say Hello",
+    );
+  }
+}
+```
+
+_Note: `this.method()` is specifically for attributes that expect a string script (like `onclick` in HTML), bridging them back to your component's methods._

docs/osm.md

@@ -0,0 +1,76 @@
+# OpenScript Markup (OSM)
+
+OpenScript Markup (OSM) is a powerful, JavaScript-based Domain Specific Language (DSL) for generating HTML. It uses the `h` object, a proxy that translates methods into HTML elements.
+
+## Basic Syntax
+
+To use OSM, you need to import the `app` instance and retrieve the `h` service.
+
+```javascript
+import { app } from "modular-openscriptjs";
+
+const h = app("h");
+
+// Simple element
+const div = h.div("Hello World");
+// Output: <div>Hello World</div>
+```
+
+### How it Works
+
+The `h` object is a **Proxy**. When you access a property on it (e.g., `h.div`, `h.span`, `h.customElement`), it returns a function that generates an element with that tag name.
+
+> **Note**: OSM supports all standard HTML tags (`h.section`, `h.a`, `h.img`) and custom elements (`h.myComponent`).
+
+## Attributes & Properties
+
+You can pass attributes as the first argument to the tag function if it is an object (and not a DOM node or State).
+
+```javascript
+h.a(
+  {
+    href: "https://example.com",
+    class: "link primary",
+    target: "_blank",
+    id: "main-link",
+  },
+  "Visit Example",
+);
+```
+
+### Boolean Attributes
+
+Boolean attributes work as expected:
+
+```javascript
+h.input({ type: "checkbox", checked: true, disabled: false });
+```
+
+### Style Object
+
+You can pass a style string directly:
+
+```javascript
+h.div({ style: "color: red; font-weight: bold;" }, "Styled Text");
+```
+
+## Children & Text Content
+
+Arguments after the attributes (or the first argument if it's not an attributes object) are treated as children.
+
+```javascript
+h.ul(
+  { class: "list" },
+  h.li("Item 1"),
+  h.li("Item 2"),
+  h.li(h.strong("Item 3 with bold text")),
+);
+```
+
+### Text Nodes
+
+Strings and numbers are automatically converted to text nodes.
+
+```javascript
+h.p("You have ", 5, " notifications.");
+```

docs/setting-up.md

@@ -170,12 +170,26 @@ export function configureApp() {
    * ---------------------------------------------
    */
   app().value("appEvents", appEvents);
+
+  /**
+   * ---------------------------------------------
+   * Node Disposal Callback
+   * ---------------------------------------------
+   * Use this to clean up external library instances
+   * attached to DOM nodes when they are removed.
+   */
+  registerNodeDisposalCallback((node) => {
+    // Example: Dispose Bootstrap tooltips/popovers
+    // if (node._bootstrap_tooltip) node._bootstrap_tooltip.dispose();
+  });
 }
 
 // execute configuration
 configureApp();
 ```
 
+> **Note**: `registerNodeDisposalCallback` is crucial for preventing memory leaks when using third-party libraries that attach instances to DOM elements (like Bootstrap, Tippy.js, etc.). The callback **MUST** be synchronous and stateless.
+
 > **Note**: In the configuration above, we are using `appEvents` imported from `events.js`. We will cover the creation of `events.js` and how to handle events in the subsequent sections.
 
 ## 5. Define Application Events

package.json

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

src/component/Component.js

@@ -84,7 +84,6 @@ export default class Component {
 
     this.isAnonymous = false;
 
-
     this.emitter.once(this.EVENTS.rendered, (componentId) => {
       let repo = container.resolve("repository");
       let component = repo.findComponent(componentId);

src/core/Container.js

@@ -86,7 +86,42 @@ export default class Container {
     });
     return this;
   }
-
+  /**
+   * Access services from the IoC container
+   * @overload
+   * @param {'h'} instance - Get the MarkupEngine instance
+   * @returns {MarkupEngine}
+   */
+  /**
+   * @overload
+   * @param {'repository'} instance - Get the Repository instance
+   * @returns {Repository}
+   */
+  /**
+   * @overload
+   * @param {'router'} instance - Get the Router instance
+   * @returns {Router}
+   */
+  /**
+   * @overload
+   * @param {'broker'} instance - Get the Broker instance
+   * @returns {Broker}
+   */
+  /**
+   * @overload
+   * @param {'contextProvider'} instance - Get the ContextProvider instance
+   * @returns {ContextProvider}
+   */
+  /**
+   * @overload
+   * @param {'mediatorManager'} instance - Get the MediatorManager instance
+   * @returns {MediatorManager}
+   */
+  /**
+   * @overload
+   * @param {'repository'} instance - Get the Repository instance
+   * @returns {Repository}
+   */
   /**
    * Resolve a service by name
    * @param {string} name - Service identifier

src/core/Repository.js

@@ -36,6 +36,8 @@ export default class Repository {
 
     this.domListeners = new WeakMap();
     this.domMethods = new WeakMap();
+
+    this.nodeDisposalCallbacks = new Set();
   }
 
   /**
@@ -156,4 +158,12 @@ export default class Repository {
     if (!component) return;
     this.componentArgsMap.delete(component);
   }
+
+  /**
+   * Get the node disposal callbacks
+   * @returns {Set<Function>}
+   */
+  getNodeDisposalCallbacks() {
+    return this.nodeDisposalCallbacks;
+  }
 }

src/index.js

@@ -23,7 +23,7 @@ import MarkupHandler from "./component/MarkupHandler.js";
 
 import Utils from "./utils/Utils.js";
 import DOM from "./utils/DOM.js";
-import { cleanUpNode, isClass } from "./utils/helpers.js";
+import { cleanUpNode, isClass, registerNodeDisposalCallback, removeNode } from "./utils/helpers.js";
 
 // Initialize global instances
 const broker = new Broker();
@@ -191,6 +191,8 @@ export {
   payload,
   ojsRouterEvents,
   removeNodeModifications,
+  removeNode,
+  registerNodeDisposalCallback
 };
 
 // Default export object
@@ -233,6 +235,8 @@ export default {
   payload,
   ojsRouterEvents,
   removeNodeModifications,
+  removeNode,
+  registerNodeDisposalCallback
 };
 
 // Add necessary globals

src/utils/helpers.js

@@ -71,6 +71,12 @@ export function destroyNodeDeep(node) {
     destroyNodeDeep(child);
   }
 
+  if(container.resolve("repository")?.getNodeDisposalCallbacks()?.size) {
+    for (const callback of container.resolve("repository").getNodeDisposalCallbacks()) {
+      callback(node);
+    }
+  }
+
   cleanUpNode(node);
 }
 
@@ -105,3 +111,24 @@ export function registerDomListeners(node, event, listener) {
   listeners.add(listener);
   eventMap.set(event, listeners);
 }
+
+/**
+ * used to safely remove a node from the DOM
+ * @param {Node} node 
+ */
+export function removeNode(node) {
+  destroyNodeDeep(node);
+  node.remove();
+}
+
+/**
+ * used to register a callback that will be called when a node is removed from the DOM. Use this to clean up the node to avoid memory leaks. e.g. Remove Bootstrap components attached to the node. 
+ * **The Callback Must Be Stateless!**  
+ * **It must not be asynchronous!**  
+ * **If you don't understand, GOOGLE IT!**  
+ * @param {(node: Node) => void} syncStatelessCallback
+ * @returns {void}
+ */
+export function registerNodeDisposalCallback(syncStatelessCallback) {
+  container.resolve("repository").nodeDisposalCallbacks?.add(syncStatelessCallback);
+}