cleanup

modules/Animation.lua

@@ -1,10 +1,3 @@
----@class Animation
----@field duration number
----@field start {width?:number, height?:number, opacity?:number}
----@field final {width?:number, height?:number, opacity?:number}
----@field elapsed number
----@field transform table?
----@field transition table?
 --- Easing functions for animations
 local Easing = {
   linear = function(t)
@@ -47,27 +40,15 @@ local Easing = {
     return t == 1 and 1 or 1 - math.pow(2, -10 * t)
   end,
 }
-
+---@class Animation
-local Animation = {}
-Animation.__index = Animation
-
----@class AnimationProps
 ---@field duration number
 ---@field start {width?:number, height?:number, opacity?:number}
 ---@field final {width?:number, height?:number, opacity?:number}
+---@field elapsed number
 ---@field transform table?
 ---@field transition table?
-local AnimationProps = {}
+local Animation = {}
-
+Animation.__index = Animation
----@class TransformProps
----@field scale {x?:number, y?:number}?
----@field rotate number?
----@field translate {x?:number, y?:number}?
----@field skew {x?:number, y?:number}?
-
----@class TransitionProps
----@field duration number?
----@field easing string?
 
 ---@param props AnimationProps
 ---@return Animation

modules/Blur.lua

@@ -1,8 +1,3 @@
---[[
-FlexLove Blur Module
-Fast Gaussian blur implementation with canvas caching
-]]
-
 local Blur = {}
 
 -- Canvas cache to avoid recreating canvases every frame

modules/Color.lua

@@ -1,11 +1,3 @@
---[[
-Provides color handling with RGB/RGBA support and hex string conversion
-]]
-
--- ====================
--- Error Handling Utilities
--- ====================
-
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
 ---@param message string -- Error message

modules/EventHandler.lua

@@ -1,19 +1,3 @@
--- ====================
--- Event Handler Module
--- ====================
--- Handles all user input events (mouse, keyboard, touch) for UI elements
--- Manages event state, click detection, drag tracking, hover, and focus
----
---- Dependencies (must be injected via deps parameter):
----   - InputEvent: Input event class for creating event objects
----   - GuiState: GUI state manager (unused currently, reserved for future use)
-
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
--- Get keyboard modifiers helper
 local function getModifiers()
   return {
     shift = love.keyboard.isDown("lshift") or love.keyboard.isDown("rshift"),
@@ -97,7 +81,9 @@ end
 --- Restore state from persistence (for immediate mode)
 ---@param state table State data
 function EventHandler:setState(state)
-  if not state then return end
+  if not state then
+    return
+  end
 
   self._pressed = state._pressed or {}
   self._lastClickTime = state._lastClickTime
@@ -172,7 +158,9 @@ end
 ---@param my number Mouse Y position
 ---@param button number Mouse button (1=left, 2=right, 3=middle)
 function EventHandler:_handleMousePress(mx, my, button)
-  if not self._element then return end
+  if not self._element then
+    return
+  end
 
   local element = self._element
 
@@ -221,14 +209,16 @@ end
 ---@param button number Mouse button
 ---@param isHovering boolean Whether mouse is over element
 function EventHandler:_handleMouseDrag(mx, my, button, isHovering)
-  if not self._element then return end
+  if not self._element then
+    return
+  end
 
   local element = self._element
 
   local lastX = self._lastMouseX[button] or mx
   local lastY = self._lastMouseY[button] or my
 
-    if lastX ~= mx or lastY ~= my then
+  if lastX ~= mx or lastY ~= my then
     -- Mouse has moved - fire drag event only if still hovering
     if self.onEvent and isHovering then
       local modifiers = getModifiers()
@@ -264,7 +254,9 @@ end
 ---@param my number Mouse Y position
 ---@param button number Mouse button
 function EventHandler:_handleMouseRelease(mx, my, button)
-  if not self._element then return end
+  if not self._element then
+    return
+  end
 
   local element = self._element
 

modules/Grid.lua

@@ -1,7 +1,3 @@
--- ====================
--- Grid Layout System
--- ====================
-
 local modulePath = (...):match("(.-)[^%.]+$")
 local utils = require(modulePath .. "utils")
 local enums = utils.enums

modules/GuiState.lua

@@ -1,8 +1,3 @@
--- ====================
--- GUI State Module
--- ====================
--- Shared state between Gui and Element to avoid circular dependencies
-
 ---@class GuiState
 local GuiState = {
   -- Top-level elements

modules/ImageCache.lua

@@ -1,12 +1,3 @@
---[[
-ImageCache.lua - Image caching system for FlexLove
-Provides efficient image loading and caching with memory management
-]]
-
--- ====================
--- ImageCache
--- ====================
-
 ---@class ImageCache
 ---@field _cache table<string, {image: love.Image, imageData: love.ImageData?}>
 local ImageCache = {}

modules/ImageDataReader.lua

@@ -1,12 +1,3 @@
---[[
-ImageDataReader.lua - Image data reading utilities for FlexLove
-Provides functions to load and read pixel data from images
-]]
-
--- ====================
--- Error Handling Utilities
--- ====================
-
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
 ---@param message string -- Error message

modules/ImageRenderer.lua

@@ -1,12 +1,3 @@
---[[
-ImageRenderer.lua - Image rendering utilities for FlexLove
-Provides object-fit modes and object-position support for image rendering
-]]
-
--- ====================
--- Error Handling Utilities
--- ====================
-
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
 ---@param message string -- Error message

modules/ImageScaler.lua

@@ -1,12 +1,3 @@
---[[
-ImageScaler.lua - Image scaling utilities for FlexLove
-Provides nearest-neighbor and bilinear interpolation scaling algorithms
-]]
-
--- ====================
--- Error Handling Utilities
--- ====================
-
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
 ---@param message string -- Error message

modules/InputEvent.lua

@@ -1,7 +1,3 @@
--- ====================
--- Input Event System
--- ====================
-
 ---@class InputEvent
 ---@field type "click"|"press"|"release"|"rightclick"|"middleclick"|"drag"
 ---@field button number -- Mouse button: 1 (left), 2 (right), 3 (middle)

modules/LayoutEngine.lua

@@ -1,16 +1,3 @@
--- ====================
--- LayoutEngine Module
--- ====================
--- Handles all layout calculations for Element including:
--- - Flexbox layout algorithm
--- - Grid layout delegation
--- - Auto-sizing calculations
--- - CSS positioning offsets
----
---- Dependencies (must be injected via deps parameter):
----   - utils: Utility functions and enums
----   - Grid: Grid layout module
-
 ---@class LayoutEngine
 ---@field element Element Reference to the parent element
 ---@field positioning Positioning Layout positioning mode

modules/NinePatch.lua

@@ -1,9 +1,3 @@
---[[
-NinePatch - 9-Patch Renderer for FlexLove
-Handles rendering of 9-patch components with Android-style scaling.
-Corners can be scaled independently while edges stretch in one dimension.
-]]
-
 local modulePath = (...):match("(.-)[^%.]+$")
 local ImageScaler = require(modulePath .. "ImageScaler")
 

modules/NinePatchParser.lua

@@ -1,12 +1,3 @@
---[[
-NinePatchParser.lua - 9-patch PNG parser for FlexLove
-Parses Android-style 9-patch images to extract stretch regions and content padding
-]]
-
--- ====================
--- Error Handling Utilities
--- ====================
-
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
 ---@param message string -- Error message

modules/Renderer.lua

@@ -1,20 +1,3 @@
---- Renderer Module
--- Handles all visual rendering for Elements including backgrounds, borders,
--- images, themes, blur effects, and text rendering.
---
--- This module is responsible for the visual presentation layer of Elements,
--- delegating from Element's draw() method to keep rendering concerns separated.
----
---- Dependencies (must be injected via deps parameter):
----   - Color: Color module for color manipulation
----   - RoundedRect: Rounded rectangle drawing module
----   - NinePatch: 9-patch rendering module
----   - ImageRenderer: Image rendering module
----   - ImageCache: Image caching module
----   - Theme: Theme management module
----   - Blur: Blur effects module
----   - utils: Utility functions (FONT_CACHE, enums)
-
 local Renderer = {}
 Renderer.__index = Renderer
 
@@ -53,7 +36,7 @@ function Renderer.new(config, deps)
     top = false,
     right = false,
     bottom = false,
-    left = false
+    left = false,
   }
 
   -- Corner radius
@@ -61,7 +44,7 @@ function Renderer.new(config, deps)
     topLeft = 0,
     topRight = 0,
     bottomLeft = 0,
-    bottomRight = 0
+    bottomRight = 0,
   }
 
   -- Theme properties
@@ -137,12 +120,7 @@ end
 ---@param height number Height
 ---@param drawBackgroundColor table Background color (may have animation applied)
 function Renderer:_drawBackground(x, y, width, height, drawBackgroundColor)
-  local backgroundWithOpacity = self._Color.new(
+  local backgroundWithOpacity = self._Color.new(drawBackgroundColor.r, drawBackgroundColor.g, drawBackgroundColor.b, drawBackgroundColor.a * self.opacity)
-    drawBackgroundColor.r,
-    drawBackgroundColor.g,
-    drawBackgroundColor.b,
-    drawBackgroundColor.a * self.opacity
-  )
   love.graphics.setColor(backgroundWithOpacity:toRGBA())
   self._RoundedRect.draw("fill", x, y, width, height, self.cornerRadius)
 end
@@ -267,12 +245,7 @@ end
 ---@param borderBoxWidth number Border box width
 ---@param borderBoxHeight number Border box height
 function Renderer:_drawBorders(x, y, borderBoxWidth, borderBoxHeight)
-  local borderColorWithOpacity = self._Color.new(
+  local borderColorWithOpacity = self._Color.new(self.borderColor.r, self.borderColor.g, self.borderColor.b, self.borderColor.a * self.opacity)
-    self.borderColor.r,
-    self.borderColor.g,
-    self.borderColor.b,
-    self.borderColor.a * self.opacity
-  )
   love.graphics.setColor(borderColorWithOpacity:toRGBA())
 
   -- Check if all borders are enabled
@@ -338,16 +311,7 @@ function Renderer:draw(backdropCanvas)
   self:_drawBackground(element.x, element.y, borderBoxWidth, borderBoxHeight, drawBackgroundColor)
 
   -- LAYER 1.5: Draw image on top of backgroundColor (if image exists)
-  self:_drawImage(
+  self:_drawImage(element.x, element.y, element.padding.left, element.padding.top, element.width, element.height, borderBoxWidth, borderBoxHeight)
-    element.x,
-    element.y,
-    element.padding.left,
-    element.padding.top,
-    element.width,
-    element.height,
-    borderBoxWidth,
-    borderBoxHeight
-  )
 
   -- LAYER 2: Draw theme on top of backgroundColor (if theme exists)
   self:_drawTheme(element.x, element.y, borderBoxWidth, borderBoxHeight, element.scaleCorners, element.scalingAlgorithm)
@@ -596,7 +560,8 @@ function Renderer:drawText(element)
   end
 
   if displayText and displayText ~= "" then
-    local textColor = isPlaceholder and self._Color.new(element.textColor.r * 0.5, element.textColor.g * 0.5, element.textColor.b * 0.5, element.textColor.a * 0.5)
+    local textColor = isPlaceholder
+        and self._Color.new(element.textColor.r * 0.5, element.textColor.g * 0.5, element.textColor.b * 0.5, element.textColor.a * 0.5)
       or element.textColor
     local textColorWithOpacity = self._Color.new(textColor.r, textColor.g, textColor.b, textColor.a * self.opacity)
     love.graphics.setColor(textColorWithOpacity:toRGBA())

modules/RoundedRect.lua

@@ -1,8 +1,3 @@
---[[
-RoundedRect - Rounded Rectangle Helper for FlexLove
-Provides functions for generating and drawing rounded rectangles with per-corner radius control.
-]]
-
 local RoundedRect = {}
 
 --- Generate points for a rounded rectangle

modules/ScrollManager.lua

@@ -1,10 +1,3 @@
---- ScrollManager.lua
---- Handles scrolling, overflow detection, and scrollbar rendering/interaction for Elements
---- Extracted from Element.lua as part of element-refactor-modularization task 05
----
---- Dependencies (must be injected via deps parameter):
----   - Color: Color module for creating color instances
-
 ---@class ScrollManager
 ---@field overflow string -- "visible"|"hidden"|"auto"|"scroll"
 ---@field overflowX string? -- X-axis specific overflow (overrides overflow)

modules/StateManager.lua

@@ -1,10 +1,3 @@
--- ====================
--- State Manager Module
--- ====================
--- Unified state management system for immediate mode GUI elements
--- Combines ID-based state persistence with interactive state tracking
--- Handles all element state: interaction, scroll, input, click tracking, etc.
-
 ---@class StateManager
 local StateManager = {}
 
@@ -23,7 +16,7 @@ local callSiteCounters = {}
 -- Configuration
 local config = {
   stateRetentionFrames = 60, -- Keep unused state for 60 frames (~1 second at 60fps)
-  maxStateEntries = 1000,    -- Maximum state entries before forced GC
+  maxStateEntries = 1000, -- Maximum state entries before forced GC
 }
 
 -- ====================
@@ -36,7 +29,9 @@ local config = {
 ---@param depth number|nil Current recursion depth
 ---@return string
 local function hashProps(props, visited, depth)
-  if not props then return "" end
+  if not props then
+    return ""
+  end
 
   -- Initialize visited table on first call
   visited = visited or {}
@@ -70,12 +65,12 @@ local function hashProps(props, visited, depth)
     onEnter = true,
     userdata = true,
     -- Dynamic input/state properties that should not affect ID stability
-    text = true,           -- Text content changes as user types
+    text = true, -- Text content changes as user types
-    placeholder = true,    -- Placeholder text is presentational
+    placeholder = true, -- Placeholder text is presentational
-    editable = true,       -- Editable state can be toggled dynamically
+    editable = true, -- Editable state can be toggled dynamically
-    selectOnFocus = true,  -- Input behavior flag
+    selectOnFocus = true, -- Input behavior flag
-    autoGrow = true,       -- Auto-grow behavior flag
+    autoGrow = true, -- Auto-grow behavior flag
-    passwordMode = true,   -- Password mode can be toggled
+    passwordMode = true, -- Password mode can be toggled
   }
 
   -- Collect and sort keys for consistent ordering
@@ -198,42 +193,94 @@ function StateManager.getState(id, defaultState)
     local state = stateStore[id]
 
     -- Interaction states
-    if state.hover == nil then state.hover = false end
+    if state.hover == nil then
-    if state.pressed == nil then state.pressed = false end
+      state.hover = false
-    if state.focused == nil then state.focused = false end
+    end
-    if state.disabled == nil then state.disabled = false end
+    if state.pressed == nil then
-    if state.active == nil then state.active = false end
+      state.pressed = false
+    end
+    if state.focused == nil then
+      state.focused = false
+    end
+    if state.disabled == nil then
+      state.disabled = false
+    end
+    if state.active == nil then
+      state.active = false
+    end
 
     -- Scrollbar states
-    if state.scrollbarHoveredVertical == nil then state.scrollbarHoveredVertical = false end
+    if state.scrollbarHoveredVertical == nil then
-    if state.scrollbarHoveredHorizontal == nil then state.scrollbarHoveredHorizontal = false end
+      state.scrollbarHoveredVertical = false
-    if state.scrollbarDragging == nil then state.scrollbarDragging = false end
+    end
-    if state.hoveredScrollbar == nil then state.hoveredScrollbar = nil end
+    if state.scrollbarHoveredHorizontal == nil then
-    if state.scrollbarDragOffset == nil then state.scrollbarDragOffset = 0 end
+      state.scrollbarHoveredHorizontal = false
+    end
+    if state.scrollbarDragging == nil then
+      state.scrollbarDragging = false
+    end
+    if state.hoveredScrollbar == nil then
+      state.hoveredScrollbar = nil
+    end
+    if state.scrollbarDragOffset == nil then
+      state.scrollbarDragOffset = 0
+    end
 
     -- Scroll position
-    if state.scrollX == nil then state.scrollX = 0 end
+    if state.scrollX == nil then
-    if state.scrollY == nil then state.scrollY = 0 end
+      state.scrollX = 0
+    end
+    if state.scrollY == nil then
+      state.scrollY = 0
+    end
 
     -- Click tracking
-    if state._pressed == nil then state._pressed = {} end
+    if state._pressed == nil then
-    if state._lastClickTime == nil then state._lastClickTime = nil end
+      state._pressed = {}
-    if state._lastClickButton == nil then state._lastClickButton = nil end
+    end
-    if state._clickCount == nil then state._clickCount = 0 end
+    if state._lastClickTime == nil then
+      state._lastClickTime = nil
+    end
+    if state._lastClickButton == nil then
+      state._lastClickButton = nil
+    end
+    if state._clickCount == nil then
+      state._clickCount = 0
+    end
 
     -- Drag tracking
-    if state._dragStartX == nil then state._dragStartX = {} end
+    if state._dragStartX == nil then
-    if state._dragStartY == nil then state._dragStartY = {} end
+      state._dragStartX = {}
-    if state._lastMouseX == nil then state._lastMouseX = {} end
+    end
-    if state._lastMouseY == nil then state._lastMouseY = {} end
+    if state._dragStartY == nil then
+      state._dragStartY = {}
+    end
+    if state._lastMouseX == nil then
+      state._lastMouseX = {}
+    end
+    if state._lastMouseY == nil then
+      state._lastMouseY = {}
+    end
 
     -- Input/focus state
-    if state._hovered == nil then state._hovered = nil end
+    if state._hovered == nil then
-    if state._focused == nil then state._focused = nil end
+      state._hovered = nil
-    if state._cursorPosition == nil then state._cursorPosition = nil end
+    end
-    if state._selectionStart == nil then state._selectionStart = nil end
+    if state._focused == nil then
-    if state._selectionEnd == nil then state._selectionEnd = nil end
+      state._focused = nil
-    if state._textBuffer == nil then state._textBuffer = "" end
+    end
+    if state._cursorPosition == nil then
+      state._cursorPosition = nil
+    end
+    if state._selectionStart == nil then
+      state._selectionStart = nil
+    end
+    if state._selectionEnd == nil then
+      state._selectionEnd = nil
+    end
+    if state._textBuffer == nil then
+      state._textBuffer = ""
+    end
 
     -- Create metadata
     stateMetadata[id] = {

modules/TextEditor.lua

@@ -1,28 +1,3 @@
--- ====================
--- TextEditor Module
--- ====================
--- Handles all text editing functionality including:
--- - Text buffer management
--- - Cursor positioning and navigation
--- - Text selection
--- - Multi-line text with wrapping
--- - Focus management
--- - Keyboard input handling
--- - Text rendering (cursor, selection highlights)
----
---- Dependencies (must be injected via deps parameter):
----   - GuiState: GUI state manager
----   - StateManager: State persistence for immediate mode
----   - Color: Color utility class (reserved for future use)
----   - utils: Utility functions (FONT_CACHE, getModifiers)
-
--- Setup module path for relative requires
-local modulePath = (...):match("(.-)[^%.]+$")
-local function req(name)
-  return require(modulePath .. name)
-end
-
--- UTF-8 support
 local utf8 = utf8 or require("utf8")
 
 local TextEditor = {}

modules/Theme.lua

@@ -1,16 +1,9 @@
---[[
-Theme - Theme System for FlexLove
-Manages theme loading, registration, and component/color/font access.
-Supports 9-patch images, component states, and dynamic theme switching.
-]]
-
 local modulePath = (...):match("(.-)[^%.]+$")
 local function req(name)
   return require(modulePath .. name)
 end
 
 local NinePatchParser = req("NinePatchParser")
-local ImageScaler = req("ImageScaler")
 
 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")

modules/ThemeManager.lua

@@ -1,10 +1,3 @@
---- ThemeManager.lua
---- Manages theme application, state transitions, and property resolution for Elements
---- Extracted from Element.lua as part of element-refactor-modularization task 06
----
---- Dependencies (must be injected via deps parameter):
----   - Theme: Theme module for loading and accessing themes
-
 ---@class ThemeManager
 ---@field theme string? -- Theme name to use
 ---@field themeComponent string? -- Component name from theme (e.g., "button", "panel")

modules/Units.lua

@@ -1,8 +1,3 @@
--- ====================
--- Units System
--- ====================
-
---- Unit parsing and viewport calculations
 local Units = {}
 
 --- Parse a unit value (string or number) into value and unit type

modules/types.lua

@@ -0,0 +1,127 @@
+--=====================================--
+-- only used for types with lua_ls, if you're using a different LSP (or none), you can remove this file --
+--=====================================--
+
+--=====================================--
+-- For Animation.lua
+--=====================================--
+---@class AnimationProps
+---@field duration number
+---@field start {width?:number, height?:number, opacity?:number}
+---@field final {width?:number, height?:number, opacity?:number}
+---@field transform table?
+---@field transition table?
+local AnimationProps = {}
+
+---@class TransformProps
+---@field scale {x?:number, y?:number}?
+---@field rotate number?
+---@field translate {x?:number, y?:number}?
+---@field skew {x?:number, y?:number}?
+
+---@class TransitionProps
+---@field duration number?
+---@field easing string?
+
+--=====================================--
+-- For Element.lua
+--=====================================--
+---@class ElementProps
+---@field id string? -- Unique identifier for the element (auto-generated in immediate mode if not provided)
+---@field parent Element? -- Parent element for hierarchical structure
+---@field x number|string? -- X coordinate of the element (default: 0)
+---@field y number|string? -- Y coordinate of the element (default: 0)
+---@field z number? -- Z-index for layering (default: 0)
+---@field width number|string? -- Width of the element (default: calculated automatically)
+---@field height number|string? -- Height of the element (default: calculated automatically)
+---@field top number|string? -- Offset from top edge (CSS-style positioning)
+---@field right number|string? -- Offset from right edge (CSS-style positioning)
+---@field bottom number|string? -- Offset from bottom edge (CSS-style positioning)
+---@field left number|string? -- Offset from left edge (CSS-style positioning)
+---@field border Border? -- Border configuration for the element
+---@field borderColor Color? -- Color of the border (default: black)
+---@field opacity number? -- Element opacity 0-1 (default: 1)
+---@field backgroundColor Color? -- Background color (default: transparent)
+---@field cornerRadius number|{topLeft:number?, topRight:number?, bottomLeft:number?, bottomRight:number?}? -- Corner radius: number (all corners) or table for individual corners (default: 0)
+---@field gap number|string? -- Space between children elements (default: 0)
+---@field padding {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Padding around children (default: {top=0, right=0, bottom=0, left=0})
+---@field margin {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Margin around element (default: {top=0, right=0, bottom=0, left=0})
+---@field text string? -- Text content to display (default: nil)
+---@field textAlign TextAlign? -- Alignment of the text content (default: START)
+---@field textColor Color? -- Color of the text content (default: black or theme text color)
+---@field textSize number|string? -- Font size: number (px), string with units ("2vh", "10%"), or preset ("xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"xxl"|"3xl"|"4xl") (default: "md" or 12px)
+---@field minTextSize number? -- Minimum text size in pixels for auto-scaling
+---@field maxTextSize number? -- Maximum text size in pixels for auto-scaling
+---@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default, inherits from parent)
+---@field autoScaleText boolean? -- Whether text should auto-scale with window size (default: true)
+---@field positioning Positioning? -- Layout positioning mode: "absolute"|"relative"|"flex"|"grid" (default: RELATIVE)
+---@field flexDirection FlexDirection? -- Direction of flex layout: "horizontal"|"vertical" (default: HORIZONTAL)
+---@field justifyContent JustifyContent? -- Alignment of items along main axis (default: FLEX_START)
+---@field alignItems AlignItems? -- Alignment of items along cross axis (default: STRETCH)
+---@field alignContent AlignContent? -- Alignment of lines in multi-line flex containers (default: STRETCH)
+---@field flexWrap FlexWrap? -- Whether children wrap to multiple lines: "nowrap"|"wrap"|"wrap-reverse" (default: NOWRAP)
+---@field justifySelf JustifySelf? -- Alignment of the item itself along main axis (default: AUTO)
+---@field alignSelf AlignSelf? -- Alignment of the item itself along cross axis (default: AUTO)
+---@field onEvent fun(element:Element, event:InputEvent)? -- Callback function for interaction events
+---@field onFocus fun(element:Element, event:InputEvent)? -- Callback when element receives focus
+---@field onBlur fun(element:Element, event:InputEvent)? -- Callback when element loses focus
+---@field onTextInput fun(element:Element, text:string)? -- Callback when text is input
+---@field onTextChange fun(element:Element, text:string)? -- Callback when text content changes
+---@field onEnter fun(element:Element)? -- Callback when Enter key is pressed
+---@field transform TransformProps? -- Transform properties for animations and styling
+---@field transition TransitionProps? -- Transition settings for animations
+---@field gridRows number? -- Number of rows in the grid (default: 1)
+---@field gridColumns number? -- Number of columns in the grid (default: 1)
+---@field columnGap number|string? -- Gap between grid columns (default: 0)
+---@field rowGap number|string? -- Gap between grid rows (default: 0)
+---@field theme string? -- Theme name to use (e.g., "space", "metal"). Defaults to theme from Gui.init()
+---@field themeComponent string? -- Theme component to use (e.g., "panel", "button", "input"). If nil, no theme is applied
+---@field disabled boolean? -- Whether the element is disabled (default: false)
+---@field active boolean? -- Whether the element is active/focused (for inputs, default: false)
+---@field disableHighlight boolean? -- Whether to disable the pressed state highlight overlay (default: false, or true when using themeComponent)
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme or {1, 1})
+---@field scaleCorners number? -- Scale multiplier for 9-patch corners/edges. E.g., 2 = 2x size (overrides theme setting)
+---@field scalingAlgorithm "nearest"|"bilinear"? -- Scaling algorithm for 9-patch corners: "nearest" (sharp/pixelated) or "bilinear" (smooth) (overrides theme setting)
+---@field contentBlur {intensity:number, quality:number}? -- Blur the element's content including children (intensity: 0-100, quality: 1-10, default: nil)
+---@field backdropBlur {intensity:number, quality:number}? -- Blur content behind the element (intensity: 0-100, quality: 1-10, default: nil)
+---@field editable boolean? -- Whether the element is editable (default: false)
+---@field multiline boolean? -- Whether the element supports multiple lines (default: false)
+---@field textWrap boolean|"word"|"char"? -- Text wrapping mode (default: false for single-line, "word" for multi-line)
+---@field maxLines number? -- Maximum number of lines (default: nil)
+---@field maxLength number? -- Maximum text length in characters (default: nil)
+---@field placeholder string? -- Placeholder text when empty (default: nil)
+---@field passwordMode boolean? -- Whether to display text as password (default: false, disables multiline)
+---@field inputType "text"|"number"|"email"|"url"? -- Input type for validation (default: "text")
+---@field textOverflow "clip"|"ellipsis"|"scroll"? -- Text overflow behavior (default: "clip")
+---@field scrollable boolean? -- Whether text is scrollable (default: false for single-line, true for multi-line)
+---@field autoGrow boolean? -- Whether element auto-grows with text (default: false for single-line, true for multi-line)
+---@field selectOnFocus boolean? -- Whether to select all text on focus (default: false)
+---@field cursorColor Color? -- Cursor color (default: nil, uses textColor)
+---@field selectionColor Color? -- Selection background color (default: nil, uses theme or default)
+---@field cursorBlinkRate number? -- Cursor blink rate in seconds (default: 0.5)
+---@field overflow "visible"|"hidden"|"scroll"|"auto"? -- Overflow behavior (default: "hidden")
+---@field overflowX "visible"|"hidden"|"scroll"|"auto"? -- X-axis overflow (overrides overflow)
+---@field overflowY "visible"|"hidden"|"scroll"|"auto"? -- Y-axis overflow (overrides overflow)
+---@field scrollbarWidth number? -- Width of scrollbar track in pixels (default: 12)
+---@field scrollbarColor Color? -- Scrollbar thumb color (default: Color.new(0.5, 0.5, 0.5, 0.8))
+---@field scrollbarTrackColor Color? -- Scrollbar track color (default: Color.new(0.2, 0.2, 0.2, 0.5))
+---@field scrollbarRadius number? -- Corner radius for scrollbar (default: 6)
+---@field scrollbarPadding number? -- Padding between scrollbar and edge (default: 2)
+---@field scrollSpeed number? -- Pixels per wheel notch (default: 20)
+---@field hideScrollbars boolean|{vertical:boolean, horizontal:boolean}? -- Hide scrollbars (boolean for both, or table for individual control, default: false)
+---@field imagePath string? -- Path to image file (auto-loads via ImageCache)
+---@field image love.Image? -- Image object to display
+---@field objectFit "fill"|"contain"|"cover"|"scale-down"|"none"? -- Image fit mode (default: "fill")
+---@field objectPosition string? -- Image position like "center center", "top left", "50% 50%" (default: "center center")
+---@field imageOpacity number? -- Image opacity 0-1 (default: 1, combines with element opacity)
+---@field _scrollX number? -- Internal: scroll X position (restored in immediate mode)
+---@field _scrollY number? -- Internal: scroll Y position (restored in immediate mode)
+---@field userdata table? -- User-defined data storage for custom properties
+local ElementProps = {}
+
+---@class Border
+---@field top boolean
+---@field right boolean
+---@field bottom boolean
+---@field left boolean
+local Border = {}

modules/utils.lua

@@ -1,103 +1,3 @@
----@class ElementProps
----@field id string? -- Unique identifier for the element (auto-generated in immediate mode if not provided)
----@field parent Element? -- Parent element for hierarchical structure
----@field x number|string? -- X coordinate of the element (default: 0)
----@field y number|string? -- Y coordinate of the element (default: 0)
----@field z number? -- Z-index for layering (default: 0)
----@field width number|string? -- Width of the element (default: calculated automatically)
----@field height number|string? -- Height of the element (default: calculated automatically)
----@field top number|string? -- Offset from top edge (CSS-style positioning)
----@field right number|string? -- Offset from right edge (CSS-style positioning)
----@field bottom number|string? -- Offset from bottom edge (CSS-style positioning)
----@field left number|string? -- Offset from left edge (CSS-style positioning)
----@field border Border? -- Border configuration for the element
----@field borderColor Color? -- Color of the border (default: black)
----@field opacity number? -- Element opacity 0-1 (default: 1)
----@field backgroundColor Color? -- Background color (default: transparent)
----@field cornerRadius number|{topLeft:number?, topRight:number?, bottomLeft:number?, bottomRight:number?}? -- Corner radius: number (all corners) or table for individual corners (default: 0)
----@field gap number|string? -- Space between children elements (default: 0)
----@field padding {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Padding around children (default: {top=0, right=0, bottom=0, left=0})
----@field margin {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Margin around element (default: {top=0, right=0, bottom=0, left=0})
----@field text string? -- Text content to display (default: nil)
----@field textAlign TextAlign? -- Alignment of the text content (default: START)
----@field textColor Color? -- Color of the text content (default: black or theme text color)
----@field textSize number|string? -- Font size: number (px), string with units ("2vh", "10%"), or preset ("xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"xxl"|"3xl"|"4xl") (default: "md" or 12px)
----@field minTextSize number? -- Minimum text size in pixels for auto-scaling
----@field maxTextSize number? -- Maximum text size in pixels for auto-scaling
----@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default, inherits from parent)
----@field autoScaleText boolean? -- Whether text should auto-scale with window size (default: true)
----@field positioning Positioning? -- Layout positioning mode: "absolute"|"relative"|"flex"|"grid" (default: RELATIVE)
----@field flexDirection FlexDirection? -- Direction of flex layout: "horizontal"|"vertical" (default: HORIZONTAL)
----@field justifyContent JustifyContent? -- Alignment of items along main axis (default: FLEX_START)
----@field alignItems AlignItems? -- Alignment of items along cross axis (default: STRETCH)
----@field alignContent AlignContent? -- Alignment of lines in multi-line flex containers (default: STRETCH)
----@field flexWrap FlexWrap? -- Whether children wrap to multiple lines: "nowrap"|"wrap"|"wrap-reverse" (default: NOWRAP)
----@field justifySelf JustifySelf? -- Alignment of the item itself along main axis (default: AUTO)
----@field alignSelf AlignSelf? -- Alignment of the item itself along cross axis (default: AUTO)
----@field onEvent fun(element:Element, event:InputEvent)? -- Callback function for interaction events
----@field onFocus fun(element:Element, event:InputEvent)? -- Callback when element receives focus
----@field onBlur fun(element:Element, event:InputEvent)? -- Callback when element loses focus
----@field onTextInput fun(element:Element, text:string)? -- Callback when text is input
----@field onTextChange fun(element:Element, text:string)? -- Callback when text content changes
----@field onEnter fun(element:Element)? -- Callback when Enter key is pressed
----@field transform TransformProps? -- Transform properties for animations and styling
----@field transition TransitionProps? -- Transition settings for animations
----@field gridRows number? -- Number of rows in the grid (default: 1)
----@field gridColumns number? -- Number of columns in the grid (default: 1)
----@field columnGap number|string? -- Gap between grid columns (default: 0)
----@field rowGap number|string? -- Gap between grid rows (default: 0)
----@field theme string? -- Theme name to use (e.g., "space", "metal"). Defaults to theme from Gui.init()
----@field themeComponent string? -- Theme component to use (e.g., "panel", "button", "input"). If nil, no theme is applied
----@field disabled boolean? -- Whether the element is disabled (default: false)
----@field active boolean? -- Whether the element is active/focused (for inputs, default: false)
----@field disableHighlight boolean? -- Whether to disable the pressed state highlight overlay (default: false, or true when using themeComponent)
----@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme or {1, 1})
----@field scaleCorners number? -- Scale multiplier for 9-patch corners/edges. E.g., 2 = 2x size (overrides theme setting)
----@field scalingAlgorithm "nearest"|"bilinear"? -- Scaling algorithm for 9-patch corners: "nearest" (sharp/pixelated) or "bilinear" (smooth) (overrides theme setting)
----@field contentBlur {intensity:number, quality:number}? -- Blur the element's content including children (intensity: 0-100, quality: 1-10, default: nil)
----@field backdropBlur {intensity:number, quality:number}? -- Blur content behind the element (intensity: 0-100, quality: 1-10, default: nil)
----@field editable boolean? -- Whether the element is editable (default: false)
----@field multiline boolean? -- Whether the element supports multiple lines (default: false)
----@field textWrap boolean|"word"|"char"? -- Text wrapping mode (default: false for single-line, "word" for multi-line)
----@field maxLines number? -- Maximum number of lines (default: nil)
----@field maxLength number? -- Maximum text length in characters (default: nil)
----@field placeholder string? -- Placeholder text when empty (default: nil)
----@field passwordMode boolean? -- Whether to display text as password (default: false, disables multiline)
----@field inputType "text"|"number"|"email"|"url"? -- Input type for validation (default: "text")
----@field textOverflow "clip"|"ellipsis"|"scroll"? -- Text overflow behavior (default: "clip")
----@field scrollable boolean? -- Whether text is scrollable (default: false for single-line, true for multi-line)
----@field autoGrow boolean? -- Whether element auto-grows with text (default: false for single-line, true for multi-line)
----@field selectOnFocus boolean? -- Whether to select all text on focus (default: false)
----@field cursorColor Color? -- Cursor color (default: nil, uses textColor)
----@field selectionColor Color? -- Selection background color (default: nil, uses theme or default)
----@field cursorBlinkRate number? -- Cursor blink rate in seconds (default: 0.5)
----@field overflow "visible"|"hidden"|"scroll"|"auto"? -- Overflow behavior (default: "hidden")
----@field overflowX "visible"|"hidden"|"scroll"|"auto"? -- X-axis overflow (overrides overflow)
----@field overflowY "visible"|"hidden"|"scroll"|"auto"? -- Y-axis overflow (overrides overflow)
----@field scrollbarWidth number? -- Width of scrollbar track in pixels (default: 12)
----@field scrollbarColor Color? -- Scrollbar thumb color (default: Color.new(0.5, 0.5, 0.5, 0.8))
----@field scrollbarTrackColor Color? -- Scrollbar track color (default: Color.new(0.2, 0.2, 0.2, 0.5))
----@field scrollbarRadius number? -- Corner radius for scrollbar (default: 6)
----@field scrollbarPadding number? -- Padding between scrollbar and edge (default: 2)
----@field scrollSpeed number? -- Pixels per wheel notch (default: 20)
----@field hideScrollbars boolean|{vertical:boolean, horizontal:boolean}? -- Hide scrollbars (boolean for both, or table for individual control, default: false)
----@field imagePath string? -- Path to image file (auto-loads via ImageCache)
----@field image love.Image? -- Image object to display
----@field objectFit "fill"|"contain"|"cover"|"scale-down"|"none"? -- Image fit mode (default: "fill")
----@field objectPosition string? -- Image position like "center center", "top left", "50% 50%" (default: "center center")
----@field imageOpacity number? -- Image opacity 0-1 (default: 1, combines with element opacity)
----@field _scrollX number? -- Internal: scroll X position (restored in immediate mode)
----@field _scrollY number? -- Internal: scroll Y position (restored in immediate mode)
----@field userdata table? -- User-defined data storage for custom properties
-local ElementProps = {}
-
----@class Border
----@field top boolean
----@field right boolean
----@field bottom boolean
----@field left boolean
-local Border = {}
-
 local enums = {
   ---@enum TextAlign
   TextAlign = { START = "start", CENTER = "center", END = "end", JUSTIFY = "justify" },