eleva

Architecture & Data Flow

Version: 1.0.0

This guide explains how data flows through the framework and how its key components interact.

Eleva’s design emphasizes clarity, modularity, and performance.

---

Key Components

1. Component Definition

Components are plain JavaScript objects that describe a UI segment:

• template function - Returns HTML with interpolation placeholders
• setup() function - Initializes state using reactive signals (optional)
• style function - Scoped CSS (optional)
• children object - Nested components (optional)

2. Signals (Reactivity)

Signals are reactive data holders that notify watchers when their values change, triggering re-renders of the affected UI.

3. TemplateEngine (Evaluation)

Evaluates expressions in @events and :props attributes against the component context, enabling event binding and prop passing.

4. Renderer (DOM Diffing and Patching)

Compares the new HTML structure with the current DOM and patches only the parts that have changed, ensuring high performance without virtual DOM overhead.

5. Emitter (Event Handling)

Implements a publish-subscribe pattern to allow components to communicate by emitting and listening to custom events.

---

Data Flow Process

1. Initialization

• Registration: Components are registered via app.component()
• Mounting: app.mount() creates a context (props, lifecycle hooks, emitter) and executes setup() to create reactive state

2. Rendering

• The template function is called with the combined context and reactive state
• JavaScript template literals (${}) interpolate values directly
• The TemplateEngine evaluates @events and :props expressions
• The Renderer patches the resulting HTML into the DOM

3. Reactivity

• When a signal’s value changes, its watcher triggers a re-run of the template
• The Renderer diffs the new HTML against the current DOM
• Only necessary changes are applied

4. Events

• Event listeners (e.g., @click) are bound during rendering
• Handlers execute with the current state and event details
• Components can emit custom events via the Emitter

---

Visual Overview

[Component Registration]
         │
         ▼
[Mounting & Context Creation]
         │
         ▼
[setup() Execution → Creates Signals]
         │
         ▼
[Template Function Produces HTML]
         │
         ▼
    onBeforeMount
         │
         ▼
[Renderer: Diff → Patch DOM]
         │
         ▼
[Process @events & :props]
         │
         ▼
[Inject Scoped Styles]
         │
         ▼
[Mount Child Components]
         │
         ▼
      onMount
         │
         ▼
┌────────────────────────────────────────────┐
│            ↺ REACTIVE CYCLE                │
├────────────────────────────────────────────┤
│                                            │
│  [Idle: Waiting for Signal Change] ◄───┐   │
│           │                            │   │
│           ▼                            │   │
│  [User Event / Signal Change / Emit]   │   │
│           │                            │   │
│           ▼                            │   │
│  [queueMicrotask Batches Updates]      │   │
│           │                            │   │
│           ▼                            │   │
│  [Template Re-evaluation]              │   │
│           │                            │   │
│           ▼                            │   │
│     onBeforeUpdate                     │   │
│           │                            │   │
│           ▼                            │   │
│  [Renderer: Diff → Patch DOM]          │   │
│           │                            │   │
│           ▼                            │   │
│  [Process @events & :props]            │   │
│           │                            │   │
│           ▼                            │   │
│       onUpdate ────────────────────────┘   │
│                                            │
└────────────────────────────────────────────┘

---

Detailed Architecture Flow

For contributors or developers seeking a deeper understanding:

              [Component Registration]
                         │
                         ▼
              [Mounting & Context Creation]
              • props passed to context
              • emitter reference (shared instance)
              • signal factory function
                         │
                         ▼
              [setup() Execution]
              • Creates signals via factory
              • Returns state + lifecycle hooks
                         │
                         ▼
             [Template Function Produces HTML]
             • Template literals ${} evaluated
             • Returns HTML string
                         │
                         ▼
                  ─ onBeforeMount ─
                         │
                         ▼
            [Renderer: Diff → Patch]
            • Two-pointer diffing algorithm
            • Key-based reconciliation
            • Minimal DOM mutations
                         │
                         ▼
            [TemplateEngine Processes]
            • Evaluates @event expressions
            • Binds event listeners to DOM
            • Evaluates :prop expressions
                         │
                         ▼
               [Inject Scoped Styles]
                         │
                         ▼
              [Mount Child Components]
                         │
                         ▼
                    ─ onMount ─
                         │
                         ▼
┌────────────────────────────────────────────────────┐
│                 ↺ REACTIVE CYCLE                   │
├────────────────────────────────────────────────────┤
│                                                    │
│       [Idle: Waiting for Signal Change] ◄──────┐   │
│                        │                       │   │
│    ┌───────────────────┼───────────────────┐   │   │
│    ▼                   ▼                   ▼   │   │
│ [User Event]    [Signal.value = x]  [emitter]  │   │
│    │                   │                   │   │   │
│    └───────────────────┼───────────────────┘   │   │
│                        ▼                       │   │
│             [queueMicrotask Batching]          │   │
│             • Multiple changes collapsed       │   │
│             • Single render scheduled          │   │
│                        │                       │   │
│                        ▼                       │   │
│             [Template Re-evaluation]           │   │
│                        │                       │   │
│                        ▼                       │   │
│                ─ onBeforeUpdate ─              │   │
│                        │                       │   │
│                        ▼                       │   │
│              [Renderer: Diff → Patch]          │   │
│                        │                       │   │
│                        ▼                       │   │
│            [TemplateEngine Processes]          │   │
│            • Re-binds @events                  │   │
│            • Re-evaluates :props               │   │
│                        │                       │   │
│                        ▼                       │   │
│                   ─ onUpdate ──────────────────┘   │
│                                                    │
└────────────────────────────────────────────────────┘

---

Complete Data Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│                     ELEVA DATA FLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [Component Registration]                                   │
│          │                                                  │
│          ▼                                                  │
│  [Mounting & Context Creation]                              │
│          │                                                  │
│          ▼                                                  │
│  [setup() Execution] ──► Returns { state, hooks }           │
│          │                                                  │
│          ▼                                                  │
│  [template() Produces HTML]                                 │
│          │                                                  │
│          ▼                                                  │
│  [onBeforeMount]                                            │
│          │                                                  │
│          ▼                                                  │
│  [Renderer.patchDOM()] ──► Diff & patch changes             │
│          │                                                  │
│          ▼                                                  │
│  [TemplateEngine] ──► Bind @events, eval :props             │
│          │                                                  │
│          ▼                                                  │
│      [onMount]                                              │
│          │                                                  │
│          ▼                                                  │
│  ┌─────────────────── ↺ REACTIVE CYCLE ───────────────────┐ │
│  │                                                        │ │
│  │  [Idle: Waiting] ◄─────────────────────────────────┐   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [User Interaction] ──► Event Handler              │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [signal.value = newValue]                         │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [queueMicrotask batching]                         │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [template() Re-evaluation]                        │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [onBeforeUpdate]                                  │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [Renderer.patchDOM()]                             │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [TemplateEngine] ──► Re-bind @events              │   │ │
│  │        │                                           │   │ │
│  │        ▼                                           │   │ │
│  │  [onUpdate] ───────────────────────────────────────┘   │ │
│  │                                                        │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Benefits

Benefit	Description
Modularity	Each component encapsulates its own logic and state
Efficiency	Only changed DOM parts are updated
Predictability	One-way data flow (state → template → DOM)
Extensibility	Clear separation of concerns enables plugins

---

Module Interaction

┌─────────────────────────────────────────────────────────────┐
│                      Eleva (Core)                           │
│                                                             │
│  ┌─────────┐    ┌────────────────┐    ┌──────────────────┐  │
│  │ Signal  │◄──►│ TemplateEngine │◄──►│     Renderer     │  │
│  └─────────┘    └────────────────┘    └──────────────────┘  │
│       │                │                      │             │
│       │                │                      │             │
│       ▼                ▼                      ▼             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    Component                          │  │
│  │  • setup() creates signals                            │  │
│  │  • template() uses TemplateEngine for @events/:props  │  │
│  │  • Renderer patches DOM on signal changes             │  │
│  └───────────────────────────────────────────────────────┘  │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                                │
│  │ Emitter │ ◄── Inter-component communication              │
│  └─────────┘                                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Next Steps

• Plugin System - Creating and using plugins
• Best Practices - Patterns and guidelines
• API Reference - Complete API documentation

---

← Components

Back to Main Docs

Plugin System →

This site is open source. Improve this page.