Component Basics

Vulpis provides two distinct methods for creating UI components: Raw Tables and Helpers. Both methods result in the same Virtual DOM structure processed by the C++ engine.

1. Raw Lua Tables

At the lowest level, the Vulpis engine parses standard Lua tables. This method is the "truth" of the engine—it gives you direct control over the structure passed to the renderer.

The "type" Requirement

When using Raw Tables, you must include a type attribute. This tells the engine which component to instantiate (e.g., "vbox", "text", "box"). Aside from this explicit tag, the property structure remains identical to the Helper API.

Example

local my_component = {
    type = "vbox", -- Required in Raw Tables
    style = {
        w = 400,
        h = 300,
        BGColor = "#333333",
        justifyContent = "center",
        alignItems = "center",
    },
    children = {
        {
            type = "text", -- Required in Raw Tables
            text = "Raw Table Example",
            style = { FontColor = "#ffffff", fontSize = 20 }
        }
    }
}

2. Helper API

The utils/core/elements.lua module provides a functional API. These helpers are simple wrappers that automatically inject the type attribute for you, making the code cleaner and less error-prone.

Why use Helpers?

• Automatic Typing: You don't need to manually write type = "text".
• Readability: It creates a visual hierarchy that is easier to scan.
• Tooling: Lua LSPs can more easily provide autocompletion for function arguments.

Example

local el = require("utils.core.elements")

local my_component = el.VBox({
    style = {
        w = 400,
        h = 300,
        BGColor = "#333333",
    },
    children = {
        el.Text({
            text = "Helper Example",
            style = { FontColor = "#ffffff", fontSize = 20 }
        })
    }
})