Dynamic & Reactive Systems

Basalt provides three systems for creating dynamic, responsive UIs: the State System, the Responsive Plugin, and the Reactive Plugin. Each serves a different purpose and can be combined for maximum flexibility.

---

State System

The state system allows elements to have conditional states that automatically activate based on custom logic. This is the foundation that powers the responsive plugin.

Conditional States

Register states that evaluate conditions and automatically activate/deactivate:

-- Using a function
-- When using functions, you need to manually specify which properties to observe
local label = main:addLabel()
    :registerResponsiveState("small", function(self)
        return self.parent:getWidth() < 25
    end, {
        observe = { 
            {main, "width"}  -- Format: {element, "property"}
        },
    })
    :setTextState("small", "Compact")
    :setText("Full Text")

-- Using a string expression (automatic dependency detection)
-- String expressions automatically detect and observe referenced properties
local sidebar = main:addFrame()
    :registerResponsiveState("collapsed", "parent.width < 30", 100)
    :setWidthState("collapsed", 5)
    :setWidthState("default", 15)
    :setY(15)

String Expressions

String expressions automatically parse and detect dependencies - no manual observe needed:

-- Dependencies are auto-detected from the expression
element:registerResponsiveState("portrait", "parent.width < parent.height", 100)

You can optionally add extra dependencies that aren't in the expression:

-- Auto-detects parent.width, but also observes otherElement.text
element:registerResponsiveState("complex", "parent.width < 30", {
    priority = 100,
    observe = {
        {otherElement, "text"}  -- Additional dependency
    }
})

Behind the scenes: The system parses expressions like "parent.width < 30", extracts property references (parent.width), and automatically sets up observers for reactive updates.

Manual State Control

You can also control states manually:

element:setState("customState", 100)  -- Activate with priority 100
element:unsetState("customState")     -- Deactivate
element:hasState("customState")       -- Check if active
element:getActiveStates()             -- Get all active states sorted by priority

---

Responsive Plugin

The responsive plugin builds on the state system to create layouts that adapt to parent size or other conditions. It provides a fluent builder API.

Basic Responsive Layout

local sidebar = main:addFrame()
    :responsive()
        :when("parent.width < 15")
            :apply({ width = 10, background = colors.gray })
        :when("parent.width >= 40")
            :apply({ width = 25, background = colors.lightGray })
        :otherwise({ width = 15 })

Advanced Conditions

String expressions support math operations and can reference any element property:

local dynamicFrame = frame:addFrame()
    :responsive()
        :when("parent.width < parent.height")
            :apply({ width = "parent.width * 0.9", height = 10 })
        :otherwise({ width = 20, height = "parent.height * 0.9" })

Behind the scenes: The responsive plugin automatically detects dependencies from expressions (like parent.width) and sets up observers for reactive updates.

---

Reactive Plugin

The reactive plugin allows property values themselves to be dynamic expressions that automatically update when dependencies change.

Basic Usage

-- Center a label horizontally
local label = frame:addLabel()
    :setText("Centered")
    :setX("{parent.width / 2 - self.width / 2}")

-- Progress bar that takes 80% of parent width
frame:addProgressBar()
    :setWidth("{parent.width * 0.8}")
    :setX("{parent.width * 0.1}")

Available Variables

• self - The current element
• parent - The parent element
• elementName - Named elements (e.g., mySlider.value)

Linked Properties

local slider = frame:addSlider("volumeSlider")
    :setPosition(2, 2)

local label = frame:addLabel()
    :setText("{volumeSlider.value}")  -- Text updates with slider
    :setX("{volumeSlider.x + volumeSlider.width + 2}")

Dynamic Sizing

local label = frame:addLabel()
    :setText("Dynamic width")
    :setWidth("{#self.text + 2}")  -- Width = text length + padding

---

Combining Systems

You can combine all three systems for maximum flexibility:

local frame = main:addFrame()
    :setWidth("{parent.width * 0.8}")  -- Reactive: 80% of parent
    :responsive()                       -- Responsive: breakpoints
        :when("parent.width < 30")
            :apply({ background = colors.gray })
        :otherwise({ background = colors.lightGray })
    :setPropertyState("background", "hover", colors.white)  -- State: hover effect

The responsive and reactive plugins work together - you can use reactive expressions within :apply():

local element = main:addLabel()
    :responsive()
        :when("parent.width < 30")
            :apply({ text = "Small", x = "{parent.width - self.width}" })  -- Reactive expression
        :otherwise({ text = "Large", x = 5 })

---

Practical Example: Adaptive Layout

A common use case is creating a layout that adapts between side-by-side and stacked views based on screen width:

local basalt = require("basalt")
local main = basalt.getMainFrame()

-- Left container
local rightContainer = main:addFrame()
    :setSize(20, 10)
    :setBackground(colors.green)
    :responsive()
        :when("parent.width >= 45")  -- Wide: positioned next to left
            :apply({
                x = 24,
                y = 2,
                width = 20
            })
        :otherwise({
                x = 2,
                y = 13,
                width = "{parent.width - 3}"
            })  -- Narrow: positioned below left
    :done()

rightContainer:addLabel()
    :setText("Right Panel")
    :setPosition(2, 2)

-- Status label showing current layout mode
local statusLabel = main:addLabel()
    :setPosition(2, 24)
    :responsive()
        :when("parent.width >= 45")
            :apply({ text = "Layout: Side by Side", foreground = colors.lime })
        :otherwise({ text = "Layout: Stacked", foreground = colors.orange })
    :done()
basalt.run()

When the main frame is wide (≥45 characters), the containers appear side by side. When it's narrow, they stack vertically - and the status label updates to reflect the current mode.