Typography: The Text Component

The Text component is the fundamental building block for rendering strings in Vulpis. Unlike standard HTML, text in Vulpis cannot be placed directly inside a container; it must be wrapped in a specific text node for the engine to calculate layout and rendering.

Component Syntax

You can define text using the Helper API (cleaner) or the Raw Table API (direct engine control).

Helper API

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

-- Shorthand: Just the string
el.Text("Quick Label")

-- Full: With behavior and styles
el.Text({
    text = "Detailed Header",
    allowSelection = true,
    style = { fontSize = 24 }
})

Raw Table

-- Direct Virtual DOM structure
return {
    type = "text",
    text = "Detailed Header",
    allowSelection = true,
    style = { fontSize = 24 }
}

1. Engine & Behavior Attributes

These properties live at the top level of the component table and control how the engine handles the node.

Attribute	Type	Default	Description
text	string	""	The string content to render.
allowSelection	boolean	false	Enables text highlighting and clipboard copying (Ctrl+C).
id	string	nil	Unique identifier for the C++ engine or finding nodes.
key	string	nil	Used for efficient VDOM reconciliation in lists.

2. Style Attributes

Visual properties must be placed inside the style = { ... } sub-table.

Appearance

• FontColor: Sets the character color using hex (e.g., "#FFFFFF") or an RGBA table.
• textDecoration: Adds decorative lines. Options: "none", "underline", or "strike-through".
• opacity: Controls transparency from 0.0 to 1.0.

Typography Control

• fontSize: The size of the text in pixels.
• fontFamily: The alias of a registered font asset.
• fontWeight: The thickness of characters. Options: "thin", "normal", "semi-bold", "bold", "very-bold".
• fontStyle: The slope of the text. Options: "normal", "italics".

Layout & Alignment

• textAlign: Horizontal alignment within the box: "left", "center", or "right".
• wordWrap: When true, text automatically breaks into new lines at the container edge.
• w / h: Forces specific dimensions (useful for centering text in a full-width block).

Event Handling

Text nodes support standard interaction events, which is particularly useful for building links or interactive labels.

el.Text({
    text = "Clickable Link",
    allowSelection = false, -- Disable highlighting for a cleaner button feel
    onClick = function()
        print("Link clicked!")
    end,
    style = {
        FontColor = "#61afef",
        textDecoration = "underline"
    }
})

Supported Events:

• onClick, onRightClick
• onMouseEnter, onMouseLeave
• onFocus, onBlur
• onKeyDown, onTextInput