PawaComment

The PawaComment interface extends native DOM comment nodes, serving as invisible markers that define the boundaries and control the behavior of PawaJS directives like if, for-each, and switch.

Invisible Controllers

PawaJS uses comment nodes to manage the dynamic insertion, removal, and reordering of elements controlled by directives. These comments act as anchors, allowing the runtime to precisely manipulate the DOM without needing a Virtual DOM.

html 

                 
<!-- if condition -->
<div>Content rendered conditionally</div>
<!-- end if -->

Key Properties

While primarily internal, understanding these properties can be beneficial for advanced debugging or plugin development.

_el: Comment

The actual DOM comment node that serves as the starting marker for the directive.

_endComment: Comment | null

The corresponding closing comment node, defining the end boundary of the directive's controlled content.

_controlComponent: boolean

Indicates if this comment node is responsible for controlling the lifecycle of a component or a block of elements (e.g., from if or for-each).

_terminateEffects: Set<Function>

A set of cleanup functions associated with this directive's scope, ensuring proper resource release when the controlled elements are removed.

_forKey: string | null

Used specifically by the for-each directive to store the unique key of an iterated item, enabling efficient list reconciliation.

_coveringElement: PawaElement | null

A reference to the PawaElement instance that "owns" or is directly associated with this comment, providing context for evaluation.

Key Methods

These methods are primarily invoked internally by the PawaJS runtime to manage the DOM based on directive logic.

remove(): void

Removes the comment node and any elements it directly controls from the DOM, triggering associated cleanup.

terminateEffects(): void

Executes all cleanup functions registered in _terminateEffects, stopping reactive observers and preventing memory leaks.

keyRemoveElement(callback?: Function, firstElement?: boolean): Promise<void>

A specialized removal method used by for-each to efficiently remove elements associated with a specific key, often involving exit animations.

forKeyResetElement(): DocumentFragment

Used by for-each to extract and return the DOM nodes between its start and end comments as a DocumentFragment, typically for reordering.

When to Interact with PawaComment

Direct interaction with PawaComment instances is generally not required for typical application development. It becomes relevant when you are: