better type handling with lua_ls

2025-11-03 11:49:06 -05:00
parent a1804fdefb
commit 76042a9a10
23 changed files with 73 additions and 175 deletions
--- a/FlexLove.lua
+++ b/FlexLove.lua
@@ -5,33 +5,28 @@ LICENSE: MIT
 For full documentation, see README.md
 ]]

-- ====================
-- Module Imports (using relative paths)
-- ====================
 local modulePath = (...):match("(.-)[^%.]+$") -- Get the module path prefix (e.g., "libs." or "")
 local function req(name)
  return require(modulePath .. name)
 end

+-- internals
 local Blur = req("modules.Blur")
-local Color = req("modules.Color")
 local ImageDataReader = req("modules.ImageDataReader")
 local NinePatchParser = req("modules.NinePatchParser")
-local ImageScaler = req("modules.ImageScaler")
-local ImageCache = req("modules.ImageCache")
-local ImageRenderer = req("modules.ImageRenderer")
 local Theme = req("modules.Theme")
-local RoundedRect = req("modules.RoundedRect")
-local NineSlice = req("modules.NineSlice")
 local utils = req("modules.utils")
 local Units = req("modules.Units")
-local Animation = req("modules.Animation")
 local GuiState = req("modules.GuiState")
-local Grid = req("modules.Grid")
-local InputEvent = req("modules.InputEvent")
+
+-- externals
+---@type Animation
+local Animation = req("modules.Animation")
+---@type Color
+local Color = req("modules.Color")
+---@type Element
 local Element = req("modules.Element")

-- Extract from utils
 local enums = utils.enums

 local Positioning, FlexDirection, JustifyContent, AlignContent, AlignItems, TextAlign, AlignSelf, JustifySelf, FlexWrap =
@@ -244,8 +239,14 @@ function Gui.getElementAtPosition(x, y)
      -- Check if this element has scrollable overflow
      local overflowX = element.overflowX or element.overflow
      local overflowY = element.overflowY or element.overflow
-      local hasScrollableOverflow = (overflowX == "scroll" or overflowX == "auto" or overflowY == "scroll" or overflowY == "auto" or
-                                     overflowX == "hidden" or overflowY == "hidden")
+      local hasScrollableOverflow = (
+        overflowX == "scroll"
+        or overflowX == "auto"
+        or overflowY == "scroll"
+        or overflowY == "auto"
+        or overflowX == "hidden"
+        or overflowY == "hidden"
+      )

      -- Accumulate scroll offset for children if this element has overflow clipping
      local childScrollOffsetX = scrollOffsetX
@@ -390,26 +391,9 @@ Gui.ImageDataReader = ImageDataReader
 Gui.NinePatchParser = NinePatchParser

 return {
-  -- Core
  Gui = Gui,
-  GUI = Gui, -- Backward compatibility alias
  Element = Element,
-
-  -- Submodules (exposed for direct access)
-  Blur = Blur,
  Color = Color,
-  ImageDataReader = ImageDataReader,
-  NinePatchParser = NinePatchParser,
-  ImageScaler = ImageScaler,
-  ImageCache = ImageCache,
-  ImageRenderer = ImageRenderer,
-  Theme = Theme,
-  RoundedRect = RoundedRect,
-  NineSlice = NineSlice,
-  Grid = Grid,
-  InputEvent = InputEvent,
-
-  -- Enums (individual)
  Positioning = Positioning,
  FlexDirection = FlexDirection,
  JustifyContent = JustifyContent,
@@ -419,7 +403,5 @@ return {
  AlignSelf = AlignSelf,
  JustifySelf = JustifySelf,
  FlexWrap = FlexWrap,
-
-  -- Enums (backward compatibility - grouped)
  enums = enums,
 }
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ Add the `modules` directory and `FlexLove.lua` into your project and require it:

 ```lua
 local FlexLove = require("FlexLove")
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui
 local Color = FlexLove.Color
 ```

--- a/modules/Element.lua
+++ b/modules/Element.lua
@@ -172,6 +172,7 @@ Public API methods to access internal state:
 ---@field imageOpacity number? -- Image opacity 0-1 (default: 1, combines with element opacity)
 ---@field _loadedImage love.Image? -- Internal: cached loaded image
 ---@field hideScrollbars boolean|{vertical:boolean, horizontal:boolean}? -- Hide scrollbars (boolean for both, or table for individual control)
+---@field userdata table?
 local Element = {}
 Element.__index = Element

@@ -182,6 +183,7 @@ function Element.new(props)
  self.children = {}
  self.callback = props.callback
  self.id = props.id or ""
+  self.userdata = props.userdata

  -- Input event callbacks
  self.onFocus = props.onFocus
@@ -2848,7 +2850,7 @@ function Element:update(dt)
    local by = self.y
    local bw = self._borderBoxWidth or (self.width + self.padding.left + self.padding.right)
    local bh = self._borderBoxHeight or (self.height + self.padding.top + self.padding.bottom)
-    
+
    -- Account for scroll offsets from parent containers
    -- Walk up the parent chain and accumulate scroll offsets
    local scrollOffsetX = 0
@@ -2857,15 +2859,21 @@ function Element:update(dt)
    while current do
      local overflowX = current.overflowX or current.overflow
      local overflowY = current.overflowY or current.overflow
-      local hasScrollableOverflow = (overflowX == "scroll" or overflowX == "auto" or overflowY == "scroll" or overflowY == "auto" or
-                                     overflowX == "hidden" or overflowY == "hidden")
+      local hasScrollableOverflow = (
+        overflowX == "scroll"
+        or overflowX == "auto"
+        or overflowY == "scroll"
+        or overflowY == "auto"
+        or overflowX == "hidden"
+        or overflowY == "hidden"
+      )
      if hasScrollableOverflow then
        scrollOffsetX = scrollOffsetX + (current._scrollX or 0)
        scrollOffsetY = scrollOffsetY + (current._scrollY or 0)
      end
      current = current.parent
    end
-    
+
    -- Adjust mouse position by accumulated scroll offset for hit testing
    local adjustedMx = mx + scrollOffsetX
    local adjustedMy = my + scrollOffsetY
--- a/modules/utils.lua
+++ b/modules/utils.lua
@@ -87,6 +87,7 @@
 ---@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 userdata table? -- put whatever here
 local ElementProps = {}

 ---@class Border
--- a/testing/tests/01_absolute_positioning_basic_tests.lua
+++ b/testing/tests/01_absolute_positioning_basic_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";./?.lua;./game/?.lua;./game/utils/?.lua;./game/
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 local Positioning = enums.Positioning

--- a/testing/tests/02_absolute_positioning_child_layout_tests.lua
+++ b/testing/tests/02_absolute_positioning_child_layout_tests.lua
@@ -7,7 +7,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
@@ -615,11 +615,7 @@ function TestAbsolutePositioningChildLayout:testDeepHierarchyMixedPositioning()
  luaunit.assertEquals(absoluteRoot.children[1], flexLevel1)

  luaunit.assertEquals(#flexLevel1.children, 3)
-  luaunit.assertTrue(
-    flexLevel1.children[1] == absoluteChild1
-      or flexLevel1.children[2] == absoluteChild1
-      or flexLevel1.children[3] == absoluteChild1
-  )
+  luaunit.assertTrue(flexLevel1.children[1] == absoluteChild1 or flexLevel1.children[2] == absoluteChild1 or flexLevel1.children[3] == absoluteChild1)

  luaunit.assertEquals(#flexChild1.children, 1)
  luaunit.assertEquals(flexChild1.children[1], absoluteGrandchild)
--- a/testing/tests/03_flex_direction_horizontal_tests.lua
+++ b/testing/tests/03_flex_direction_horizontal_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
--- a/testing/tests/04_flex_direction_vertical_tests.lua
+++ b/testing/tests/04_flex_direction_vertical_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
--- a/testing/tests/05_justify_content_tests.lua
+++ b/testing/tests/05_justify_content_tests.lua
@@ -7,7 +7,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 -- Import required enums
 local Positioning = enums.Positioning
@@ -748,9 +748,7 @@ function TestJustifyContent:testComplexNavigationBarLayout()
  luaunit.assertEquals(actionsSection.x + actionsSection.width, navbar.x + navbar.width)

  -- Center menu should be positioned between logo and actions
-  local expectedMenuX = logoSection.x
-    + logoSection.width
-    + ((navbar.width - logoSection.width - navMenu.width - actionsSection.width) / 2)
+  local expectedMenuX = logoSection.x + logoSection.width + ((navbar.width - logoSection.width - navMenu.width - actionsSection.width) / 2)
  luaunit.assertEquals(navMenu.x, expectedMenuX)

  -- Verify nested center alignment in menu items
--- a/testing/tests/06_align_items_tests.lua
+++ b/testing/tests/06_align_items_tests.lua
@@ -7,7 +7,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 -- Import required enums
 local Positioning = enums.Positioning
--- a/testing/tests/07_flex_wrap_tests.lua
+++ b/testing/tests/07_flex_wrap_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";./?.lua;./game/?.lua;./game/utils/?.lua;./game/
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums
 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
 local FlexWrap = enums.FlexWrap
@@ -538,8 +538,7 @@ function TestFlexWrap15_WrapWithMixedPositioning()

  -- Create flex children and one absolute child
  local child1 = createChild(container, { width = 80, height = 30 }) -- flex child
-  local child2 =
-    createChild(container, { width = 80, height = 30, positioning = Positioning.ABSOLUTE, x = 150, y = 50 }) -- absolute child
+  local child2 = createChild(container, { width = 80, height = 30, positioning = Positioning.ABSOLUTE, x = 150, y = 50 }) -- absolute child
  local child3 = createChild(container, { width = 80, height = 30 }) -- flex child
  local child4 = createChild(container, { width = 80, height = 30 }) -- flex child - should wrap

--- a/testing/tests/08_comprehensive_flex_tests.lua
+++ b/testing/tests/08_comprehensive_flex_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";./?.lua;./game/?.lua;./game/utils/?.lua;./game/
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums
 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
 local FlexWrap = enums.FlexWrap
--- a/testing/tests/09_layout_validation_tests.lua
+++ b/testing/tests/09_layout_validation_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums
 local Color = FlexLove.Color
 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
--- a/testing/tests/10_performance_tests.lua
+++ b/testing/tests/10_performance_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums
 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
 local JustifyContent = enums.JustifyContent
@@ -386,10 +386,7 @@ function TestPerformance:testStressTestWithMaximumElements()
  print(string.format("Stress Test (%d elements): %.6f seconds", stress_count, time))

  -- Stress test should complete within reasonable time even with many elements
-  luaunit.assertTrue(
-    time < 0.05,
-    string.format("Stress test with %d elements should complete within 0.05 seconds", stress_count)
-  )
+  luaunit.assertTrue(time < 0.05, string.format("Stress test with %d elements should complete within 0.05 seconds", stress_count))

  -- Verify that all children are positioned
  local positioned_count = 0
@@ -760,8 +757,7 @@ function TestPerformance:testHighFrequencyDynamicLayoutUpdates()
          section:layoutChildren()
        elseif scenario.name == "Justify Content Cycling" then
          local section = sections[(i % #sections) + 1]
-          local justifies =
-            { JustifyContent.FLEX_START, JustifyContent.CENTER, JustifyContent.FLEX_END, JustifyContent.SPACE_BETWEEN }
+          local justifies = { JustifyContent.FLEX_START, JustifyContent.CENTER, JustifyContent.FLEX_END, JustifyContent.SPACE_BETWEEN }
          section.justifyContent = justifies[(i % #justifies) + 1]
          section:layoutChildren()
        elseif scenario.name == "Gap Modifications" then
@@ -1264,8 +1260,7 @@ function TestPerformance:testExtremeScalePerformanceBenchmark()
            elements_used = elements_used + 1

            if current_depth < max_depth - 1 then
-              elements_used = elements_used
-                + createBranching(branch, remaining_elements - elements_used, current_depth + 1, max_depth)
+              elements_used = elements_used + createBranching(branch, remaining_elements - elements_used, current_depth + 1, max_depth)
            end

            if elements_used >= remaining_elements then
@@ -1376,22 +1371,11 @@ function TestPerformance:testExtremeScalePerformanceBenchmark()
      depth = test_metrics.max_depth,
    }

-    print(
-      string.format(
-        "    %s: %d elements, %.6f seconds (%.0f elem/sec)",
-        test_config.name,
-        test_metrics.created_elements,
-        test_time,
-        elements_per_second
-      )
-    )
+    print(string.format("    %s: %d elements, %.6f seconds (%.0f elem/sec)", test_config.name, test_metrics.created_elements, test_time, elements_per_second))

    -- Individual test assertions
    luaunit.assertTrue(test_time < 1.0, string.format("%s should complete within 1 seconds", test_config.name))
-    luaunit.assertTrue(
-      test_metrics.created_elements > 50,
-      string.format("%s should create substantial elements", test_config.name)
-    )
+    luaunit.assertTrue(test_metrics.created_elements > 50, string.format("%s should create substantial elements", test_config.name))
  end

  -- Overall benchmark analysis
--- a/testing/tests/11_auxiliary_functions_tests.lua
+++ b/testing/tests/11_auxiliary_functions_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, Color, enums = FlexLove.GUI, FlexLove.Color, FlexLove.enums
+local Gui, Color, enums = FlexLove.Gui, FlexLove.Color, FlexLove.enums

 TestAuxiliaryFunctions = {}

@@ -578,24 +578,9 @@ function TestAuxiliaryFunctions:testComplexColorManagementSystem()
    }

    -- Verify hex parsing (FlexLove uses 0-255 range)
-    luaunit.assertAlmostEquals(
-      hex_color.r / 255,
-      color_def.r,
-      0.01,
-      string.format("%s hex red component mismatch", color_def.name)
-    )
-    luaunit.assertAlmostEquals(
-      hex_color.g / 255,
-      color_def.g,
-      0.01,
-      string.format("%s hex green component mismatch", color_def.name)
-    )
-    luaunit.assertAlmostEquals(
-      hex_color.b / 255,
-      color_def.b,
-      0.01,
-      string.format("%s hex blue component mismatch", color_def.name)
-    )
+    luaunit.assertAlmostEquals(hex_color.r / 255, color_def.r, 0.01, string.format("%s hex red component mismatch", color_def.name))
+    luaunit.assertAlmostEquals(hex_color.g / 255, color_def.g, 0.01, string.format("%s hex green component mismatch", color_def.name))
+    luaunit.assertAlmostEquals(hex_color.b / 255, color_def.b, 0.01, string.format("%s hex blue component mismatch", color_def.name))
  end

  -- Test color variations (opacity, brightness adjustments)
@@ -608,11 +593,7 @@ function TestAuxiliaryFunctions:testComplexColorManagementSystem()
      local variant_color = Color.new(color_set.manual.r, color_set.manual.g, color_set.manual.b, opacity)
      color_variations[color_name]["alpha_" .. tostring(opacity)] = variant_color

-      luaunit.assertEquals(
-        variant_color.a,
-        opacity,
-        string.format("%s opacity variant should have correct alpha", color_name)
-      )
+      luaunit.assertEquals(variant_color.a, opacity, string.format("%s opacity variant should have correct alpha", color_name))
    end

    -- Create brightness variations
@@ -625,10 +606,7 @@ function TestAuxiliaryFunctions:testComplexColorManagementSystem()
      local bright_color = Color.new(bright_r, bright_g, bright_b, 1.0)
      color_variations[color_name]["bright_" .. tostring(factor)] = bright_color

-      luaunit.assertTrue(
-        bright_r <= 1.0 and bright_g <= 1.0 and bright_b <= 1.0,
-        "Brightness variations should not exceed 1.0"
-      )
+      luaunit.assertTrue(bright_r <= 1.0 and bright_g <= 1.0 and bright_b <= 1.0, "Brightness variations should not exceed 1.0")
    end
  end

@@ -699,14 +677,7 @@ function TestAuxiliaryFunctions:testComplexColorManagementSystem()
  end
  luaunit.assertTrue(total_variations >= 50, "Should have created numerous color variations")

-  print(
-    string.format(
-      "Color Management System: %d base colors, %d variations, %d UI components",
-      #base_colors,
-      total_variations,
-      #ui_container.children
-    )
-  )
+  print(string.format("Color Management System: %d base colors, %d variations, %d UI components", #base_colors, total_variations, #ui_container.children))
 end

 -- ============================================
@@ -887,16 +858,8 @@ function TestAuxiliaryFunctions:testAdvancedTextAndAutoSizingSystem()
        end
      else
        -- Without autoresize, dimensions should remain the same
-        luaunit.assertEquals(
-          element.w,
-          original_width,
-          string.format("%s: Width should not change without autoresize", update.target)
-        )
-        luaunit.assertEquals(
-          element.h,
-          original_height,
-          string.format("%s: Height should not change without autoresize", update.target)
-        )
+        luaunit.assertEquals(element.w, original_width, string.format("%s: Width should not change without autoresize", update.target))
+        luaunit.assertEquals(element.h, original_height, string.format("%s: Height should not change without autoresize", update.target))
      end
    end
  end
@@ -947,11 +910,7 @@ function TestAuxiliaryFunctions:testAdvancedTextAndAutoSizingSystem()
  -- Perform layout and verify
  main_container:layoutChildren()

-  luaunit.assertEquals(
-    #main_container.children,
-    #text_scenarios + 1,
-    "Should have scenario containers plus nested container"
-  )
+  luaunit.assertEquals(#main_container.children, #text_scenarios + 1, "Should have scenario containers plus nested container")

  -- Count text_metrics (it's a table with string keys, not an array)
  local metrics_count = 0
@@ -960,14 +919,7 @@ function TestAuxiliaryFunctions:testAdvancedTextAndAutoSizingSystem()
  end
  luaunit.assertTrue(metrics_count >= #text_scenarios, "Should have metrics for all scenarios")

-  print(
-    string.format(
-      "Text Management System: %d scenarios, %d metrics, %d updates",
-      #text_scenarios,
-      #content_manager.text_metrics,
-      #dynamic_updates
-    )
-  )
+  print(string.format("Text Management System: %d scenarios, %d metrics, %d updates", #text_scenarios, #content_manager.text_metrics, #dynamic_updates))
 end

 -- ============================================
@@ -1052,8 +1004,7 @@ function TestAuxiliaryFunctions:testComprehensiveAnimationEngine()
      table.insert(case_container.children, element)

      -- Create animation based on type
-      local duration = test_case.duration_range[1]
-        + (math.random() * (test_case.duration_range[2] - test_case.duration_range[1]))
+      local duration = test_case.duration_range[1] + (math.random() * (test_case.duration_range[2] - test_case.duration_range[1]))

      local animation
      if test_case.animation_type == "fade" then
@@ -1192,10 +1143,7 @@ function TestAuxiliaryFunctions:testComprehensiveAnimationEngine()
          local progress = anim_data.animation.elapsed / anim_data.animation.duration
          local interpolated = anim_data.animation:interpolate()

-          luaunit.assertTrue(
-            progress >= 0 and progress <= 1,
-            string.format("Animation progress should be 0-1, got %.3f", progress)
-          )
+          luaunit.assertTrue(progress >= 0 and progress <= 1, string.format("Animation progress should be 0-1, got %.3f", progress))
          luaunit.assertNotNil(interpolated, "Interpolation should return values")
        end
      end
@@ -1225,10 +1173,7 @@ function TestAuxiliaryFunctions:testComprehensiveAnimationEngine()
  -- Verify animation system functionality
  luaunit.assertTrue(total_animations > 20, "Should have created substantial number of animations")
  luaunit.assertTrue(total_completed > 0, "Some animations should have completed")
-  luaunit.assertTrue(
-    animation_system.performance_metrics.completion_rate > 0.5,
-    "Majority of animations should complete within simulation time"
-  )
+  luaunit.assertTrue(animation_system.performance_metrics.completion_rate > 0.5, "Majority of animations should complete within simulation time")

  -- Test animation chaining and sequencing
  local chain_element = Gui.new({ width = 100, height = 50, opacity = 1.0 })
@@ -1260,11 +1205,7 @@ function TestAuxiliaryFunctions:testComprehensiveAnimationEngine()
  -- Perform final layout
  animation_container:layoutChildren()

-  luaunit.assertEquals(
-    #animation_container.children,
-    #animation_test_cases + 1,
-    "Should have containers for each test case plus chain element"
-  )
+  luaunit.assertEquals(#animation_container.children, #animation_test_cases + 1, "Should have containers for each test case plus chain element")

  print(
    string.format(
@@ -1529,11 +1470,7 @@ function TestAuxiliaryFunctions:testAdvancedGUIManagementAndCleanup()
    luaunit.assertEquals(#sidebar_element.children, 0, "Destroyed element should have no children")

    if sidebar_parent then
-      luaunit.assertEquals(
-        #sidebar_parent.children,
-        original_parent_children - 1,
-        "Parent should have one fewer child after destruction"
-      )
+      luaunit.assertEquals(#sidebar_parent.children, original_parent_children - 1, "Parent should have one fewer child after destruction")
    end
  end

@@ -1922,14 +1859,7 @@ function TestAuxiliaryFunctions:testExtremeEdgeCasesAndErrorResilience()
    end
  end

-  print(
-    string.format(
-      "Edge Case Testing: %d/%d tests handled gracefully (%.1f%%)",
-      successful_tests,
-      total_tests,
-      (successful_tests / total_tests) * 100
-    )
-  )
+  print(string.format("Edge Case Testing: %d/%d tests handled gracefully (%.1f%%)", successful_tests, total_tests, (successful_tests / total_tests) * 100))

  luaunit.assertTrue(successful_tests / total_tests > 0.8, "Should handle majority of edge cases gracefully")
 end
--- a/testing/tests/12_units_system_tests.lua
+++ b/testing/tests/12_units_system_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums

 local Positioning = enums.Positioning
 local FlexDirection = enums.FlexDirection
--- a/testing/tests/13_relative_positioning_tests.lua
+++ b/testing/tests/13_relative_positioning_tests.lua
@@ -4,7 +4,7 @@ require("testing.loveStub")
 local FlexLove = require("FlexLove")
 local luaunit = require("testing.luaunit")

-local Gui, enums = FlexLove.GUI, FlexLove.enums
+local Gui, enums = FlexLove.Gui, FlexLove.enums
 local Color = FlexLove.Color
 local Positioning = enums.Positioning

--- a/testing/tests/14_text_scaling_basic_tests.lua
+++ b/testing/tests/14_text_scaling_basic_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui

 -- Test suite for comprehensive text scaling
 TestTextScaling = {}
--- a/testing/tests/15_grid_layout_tests.lua
+++ b/testing/tests/15_grid_layout_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local lu = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui
 local enums = FlexLove.enums

 TestGridLayout = {}
--- a/testing/tests/16_event_system_tests.lua
+++ b/testing/tests/16_event_system_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local lu = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui

 TestEventSystem = {}

--- a/testing/tests/17_sibling_space_reservation_tests.lua
+++ b/testing/tests/17_sibling_space_reservation_tests.lua
@@ -6,7 +6,7 @@ package.path = package.path .. ";?.lua"
 local lu = require("testing.luaunit")
 require("testing.loveStub")
 local FlexLove = require("FlexLove")
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui
 local Color = FlexLove.Color

 TestSiblingSpaceReservation = {}
--- a/testing/tests/30_scrollbar_features_tests.lua
+++ b/testing/tests/30_scrollbar_features_tests.lua
@@ -3,7 +3,7 @@ package.path = package.path .. ";./?.lua;./game/?.lua;./game/utils/?.lua;./game/
 local luaunit = require("testing.luaunit")
 require("testing.loveStub") -- Required to mock LOVE functions
 local FlexLove = require("FlexLove")
-local Gui, enums, Color = FlexLove.GUI, FlexLove.enums, FlexLove.Color
+local Gui, enums, Color = FlexLove.Gui, FlexLove.enums, FlexLove.Color

 local Positioning = enums.Positioning

--- a/themes/README.md
+++ b/themes/README.md
@@ -173,7 +173,7 @@ Legend:
 ```lua
 local FlexLove = require("FlexLove")
 local Theme = FlexLove.Theme
-local Gui = FlexLove.GUI
+local Gui = FlexLove.Gui
 local Color = FlexLove.Color

 -- Load theme