Modal

A popup window that shows a title, input fields, and action buttons. Modals can appear when you press a key, hover over a card, or click a button.

---

Structure

modal = {
    title = "Edit Item",
    options = {
        { id = "item_name", label = "Item Name", type = "text" },
        { id = "amount", label = "Amount", type = "number", min = 1, max = 100 }
    },
    buttons = {
        {
            id = "save_item",
            label = "Save",
            on_action = function(data)
                -- do something with data.dataset.item_name, data.dataset.amount
            end,
            dataset = { -- additional data if required
                source = "inventory",
                item_id = "some_id"
            }
        },
        {
            id = "cancel",
            label = "Cancel"
            -- No action needed — this will auto-close the modal
        }
    }
}

---

Modal Options

Key	Description
title	Title text shown at the top of the modal.
options	A list of inputs to show inside the modal (see Input Types).
buttons	Buttons shown at the bottom — use on_action or action.

---

Input Types

Type	Description
text	A single-line text input.
number	A number input. You can include min and max.
textarea	A larger, multiline input.
select	A dropdown menu — include options = { { label, value }, ... }.

Each input requires:

Key	Description
id	Unique field name.
label	Label displayed next to the input.

---

Button Options

Key	Description
id	Unique button ID.
label	Button text.
on_action	Custom handler function that receives { input = {}, dataset = {} }.
action	Optional named action (e.g., "close_builder").
dataset	Optional values passed alongside the input data.
(none)	If no on_action or action is given, the button closes the modal.

---

Notes

• Modal input values are automatically collected when a button is clicked.

• Values are passed to your handler function or action as data.input.

• You can show one modal per interaction or button — they do not conflict.

• Use on_action = function(data) for fully custom behavior.

• Use action = "close_builder" to safely close the UI entirely.

• Simply leave out the action on any button to close the modal.