---@meta

-- Generated from native/src/bindings/core/node.cpp. Do not edit.

---@alias NodeId integer
---@alias NodeType "box"|"text"|"button"|"custom"
---@alias NodeDirection "up"|"down"|"left"|"right"

---@class NodeSpec
---@field type NodeType
---@field w? number|"fill"|"auto"
---@field h? number|"fill"|"auto"
---@field pad? number
---@field gap? number
---@field align? "start"|"center"|"end"|"stretch"
---@field justify? "start"|"center"|"end"|"between"
---@field row? boolean
---@field at? table Absolute-position fields.
---@field capture? boolean
---@field interactive? boolean
---@field label? string
---@field font? GuiFont

---@class NodeStyle
---@field color? GuiColor
---@field background? GuiColor Background offered to descendants.
---@field fill? GuiColor Surface painted by a box.
---@field border? GuiColor
---@field face? GuiColor Default button surface.
---@field pressedFace? GuiColor Pressed button surface.
---@field pressedColor? GuiColor Pressed button text.
---@field focusColor? GuiColor Distinct outline for directional focus.
---@field radius? integer
---@field font? GuiFont
---@field textStyle? GuiTextStyle

---@class NodeLib
node = {}

---Drops the current tree; all existing IDs become invalid.
function node.reset() end

---Creates a node, optionally as a child of an existing one.
---@param parent? NodeId Nil creates a root.
---@param spec NodeSpec
---@return NodeId
function node.create(parent, spec) end

---Adopts an existing root as a child.
---@param parent NodeId
---@param child NodeId Existing root without a parent.
function node.attach(parent, child) end

---Changes a node's requested size before layout.
---@param id NodeId
---@param w? number|"fill"|"auto"
---@param h? number|"fill"|"auto"
function node.setSize(id, w, h) end

---Measures and places a subtree.
---@param root NodeId
---@param x integer
---@param y integer
---@param w integer
---@param h integer
---@return true? ok
---@return string? error
function node.layout(root, x, y, w, h) end

---Releases temporary measurement and placement inputs after layout.
function node.dropScratch() end

---Returns the deepest interactive node under a point.
---@param root NodeId
---@param x integer
---@param y integer
---@return NodeId?
function node.hit(root, x, y) end

---Returns a node's placed rectangle.
---@param id NodeId
---@return integer x
---@return integer y
---@return integer w
---@return integer h
function node.getRect(id) end

---Replaces a node's text and marks it for repaint.
---@param id NodeId
---@param text string
function node.setLabel(id, text) end

---Returns a node's text.
---@param id NodeId
---@return string?
function node.getLabel(id) end

---Returns a node's parent.
---@param id NodeId
---@return NodeId?
function node.getParent(id) end

---Sets the style roles a subtree inherits.
---@param id NodeId
---@param style NodeStyle
function node.setStyle(id, style) end

---Marks a node for repaint.
---@param id NodeId
function node.invalidate(id) end

---Sets a node's pressed state.
---@param id NodeId
---@param pressed boolean
function node.setPressed(id, pressed) end

---Whether a node is pressed.
---@param id NodeId
---@return boolean
function node.isPressed(id) end

---Focuses the first interactive node in layout order.
---@param root NodeId
---@return NodeId? focused
function node.focusFirst(root) end

---Changes focus and invalidates the previously and newly focused nodes.
---@param id? NodeId Nil clears focus.
function node.setFocus(id) end

---Returns the focused node.
---@return NodeId?
function node.getFocus() end

---Moves to the nearest interactive node in the requested direction without wrapping.
---@param root NodeId
---@param direction NodeDirection
---@return NodeId? focused Current focus when no candidate exists.
function node.moveFocus(root, direction) end

---Registers the painter every custom node calls.
---@param painter fun(id: NodeId, x: integer, y: integer, w: integer, h: integer)
function node.setPainter(painter) end

---Paints dirty nodes; the firmware owns publication to the physical display.
---@param root NodeId
function node.draw(root) end

---Returns the number of nodes in the tree.
---@return integer
function node.getCount() end

---Returns the tree's memory use.
---@return integer bytes
function node.getFootprint() end