DOM Event Handling for Beginner Mode Functional Components

Roadmap for useEvent Hook in Functional Components

This document outlines the conceptual design and implementation plan for the useEvent hook, enabling idiomatic DOM event handling within "Beginner Mode" functional components in Neo.mjs.

1. Core Concept

The useEvent hook will allow functional components to declare their intent to listen for DOM events. The actual registration and de-registration of these listeners with Neo.manager.DomEvent will be managed by the component's lifecycle, ensuring createVdom remains a pure function focused solely on VDOM generation.

2. Key Components & Their Roles

2.1. useEvent Hook (within createVdom of functional components)

• Purpose: To collect event listener specifications (event type, handler function, optional delegate selector).
• Mechanism:
  • It will obtain a reference to the current functional component instance (via a context mechanism, e.g., _currentComponentInstance).
  • It will add the event listener specification (e.g., { eventType: 'click', handler: myHandler, delegate: '.my-class' }) to a non-reactive internal array or map on the component instance (e.g., this._pendingDomEvents). This data collection operation itself must not trigger any reactive updates of the createVdom effect.
  • The handler function provided to useEvent will be a closure that captures the current state of the functional component (e.g., count from useConfig).

2.2. Neo.functional.component.Base (The Functional Component Instance)

• New Internal Property: _pendingDomEvents (e.g., an array) to temporarily store event listener specifications collected during a createVdom run.
• Lifecycle Integration:
  • afterSetMounted Hook: This is the critical point for actual event listener registration.
    • It will iterate through this._pendingDomEvents.
    • For each specification, it will call this.addDomListeners() (a method provided by the DomEvents mixin). This is where the actual interaction with Neo.manager.DomEvent occurs, sending instructions to the main thread to register the listeners.
    • After processing all pending events, this._pendingDomEvents should be cleared to prevent re-registration on subsequent createVdom runs.
  • destroy Hook:
    • It will call this.removeDomListeners() (from the DomEvents mixin) to ensure all registered listeners are properly cleaned up when the component instance is destroyed, preventing memory leaks.

2.3. Neo.mixin.DomEvents

• Role: Continues to provide the domListeners_ config and the addDomListeners/removeDomListeners methods. These methods serve as the interface for components to interact with Neo.manager.DomEvent for event registration and de-registration.

2.4. Neo.manager.DomEvent (App Worker)

• Role: Remains the central hub for delegated DOM event management within the app worker. It receives event registration/de-registration requests from components (via addDomListeners/removeDomListeners) and handles the communication with the main thread for actual DOM event observation and dispatch.

3. Benefits of this Approach

• Purity of createVdom: The createVdom function remains a pure function, focused solely on generating the VDOM structure. Side effects like DOM event registration are deferred to appropriate lifecycle hooks.
• Correct Lifecycle Management: Event listeners are correctly added only when the component's DOM is mounted and removed when the component is destroyed, preventing memory leaks and ensuring robust behavior.
• Leveraging Existing Infrastructure: Fully utilizes the powerful, optimized, and already established Neo.manager.DomEvent and DomEvents mixin.
• Idiomatic Functional Component API: Provides a clean, declarative, and intuitive useEvent hook that aligns with the functional component paradigm.
• Reactive System Compatibility: Ensures that the event registration process does not interfere with or create unintended dependencies within the core.Effect that wraps createVdom.

4. Next Steps (Implementation)

1. Implement useEvent Hook: Write the useEvent function. This hook will retrieve the current functional component instance by accessing EffectManager.getActiveEffect().componentId and then using Neo.getComponent() to get the instance. It will then collect event specifications and store them on the component instance's _pendingDomEvents property.
2. Integrate with FunctionalBase: Modify Neo.functional.component.Base to manage the _pendingDomEvents property and integrate the addDomListeners/removeDomListeners calls within its lifecycle (afterSetMounted and destroy).
3. Testing and Documentation: Thoroughly test the new hook and provide clear documentation and examples.