Playground

PawaElement

The PawaElement is the fundamental unit of the PawaJS runtime. It wraps native DOM elements to provide reactivity, directive processing, and lifecycle management.

Overview

When PawaJS starts or hydrates an application, it traverses the DOM and upgrades relevant HTMLElement nodes into PawaElement instances. This process attaches a context (scope) to the element and initializes the reactive system.

While you rarely instantiate PawaElement directly in application code, understanding it is crucial for writing plugins or contributing to the core.

Core Responsibilities

  • Context Resolution: Maintains the local scope (variables, functions) available to the element for interpolation and directives.
  • Directive Handling: Parses and executes directives like if, for-each, and event listeners.
  • Lifecycle Management: Orchestrates mounting, unmounting, and cleanup of effects.
  • Reactivity: Binds fine-grained signals to DOM attributes and text nodes.

Internal Structure

A PawaElement instance is attached to the DOM node. Here are some key properties and methods found in the source:

Properties

javascript 
                
interface PawaElement extends HTMLElement {
    _context: any;              // The data scope for this element
    _attributes: Attr[];        // Cached attributes
    _elementType: string;       // 'component', 'template', or 'element'
    _component: any;            // Instance if this is a component
    _unMountFunctions: Function[]; // Cleanup callbacks
    _running: boolean;          // Lock flag for directive processing
    _staticContext: string[];   // Variables considered static (SSR optimization)
    _exitAnimation: Function;   // Promise for exit transitions
}

Deep Dive: Internal Properties

_context

The most fundamental property. It holds the reactive state, variables, and functions available to the element. This scope cascades down from parents to children and is used by safeEval to execute expressions.

_running

A boolean lock flag. Directives like if or for-each check this to prevent multiple executions on the same element during a single render pass.

_checkStatic() & _staticContext

_staticContext is a list of variable names considered static (often from SSR). _checkStatic() verifies if these variables exist in the current _context. If found, they are removed from the static list, making them reactive. This optimization reduces overhead for truly static content.

_component

If the element is a custom component, this holds the PawaComponent instance, which contains the component's logic, props validation, and internal state.

Key Methods

remove(callback?)

Gracefully removes the element from the DOM. If the is-exit directive is present, it waits for animations to finish before detaching.

safeEval(context, expression)

Evaluates a string expression (like inside @{}) against the provided context safely.

unMount()

Triggers cleanup. It calls all registered unmount functions, terminates effects, and recursively unmounts children.

Lifecycle & Cleanup

One of the most important features of PawaElement is automatic cleanup. When an element is removed (e.g., via an if directive toggling false), PawaJS ensures that:

  1. Effects are terminated: Any runEffect tied to the element scope is stopped.
  2. Listeners are removed: Event listeners attached via on-* are garbage collected.
  3. Recursion: The cleanup process propagates down to all child PawaElements.