module refactor completion

2025-10-31 21:01:39 -04:00
parent d947bc04e4
commit 87526c34ec
9 changed files with 393 additions and 435 deletions
--- a/flexlove/Element.lua
+++ b/flexlove/Element.lua
@@ -2,6 +2,47 @@
 -- Element Object
 -- ====================

+-- Module dependencies (using relative paths)
+local modulePath = (...):match("(.-)[^%.]+$")
+local function req(name)
+  return require(modulePath .. name)
+end
+
+local GuiState = req("GuiState")
+local Theme = req("Theme")
+local Color = req("Color")
+local Units = req("Units")
+local Blur = req("Blur")
+local ImageRenderer = req("ImageRenderer")
+local NineSlice = req("NineSlice")
+local RoundedRect = req("RoundedRect")
+local Animation = req("Animation")
+local ImageCache = req("ImageCache")
+local utils = req("utils")
+local constants = req("constants")
+local Grid = req("Grid")
+local InputEvent = req("InputEvent")
+
+-- Extract utilities
+local enums = utils.enums
+local FONT_CACHE = utils.FONT_CACHE
+local resolveTextSizePreset = utils.resolveTextSizePreset
+local getModifiers = utils.getModifiers
+
+-- Extract enum values
+local Positioning = enums.Positioning
+local FlexDirection = enums.FlexDirection
+local JustifyContent = enums.JustifyContent
+local AlignContent = enums.AlignContent
+local AlignItems = enums.AlignItems
+local TextAlign = enums.TextAlign
+local AlignSelf = enums.AlignSelf
+local JustifySelf = enums.JustifySelf
+local FlexWrap = enums.FlexWrap
+
+-- Reference to Gui (via GuiState)
+local Gui = GuiState
+
 --[[
 INTERNAL FIELD NAMING CONVENTIONS:
 ---------------------------------
@@ -191,7 +232,7 @@ function Element.new(props)
    self.contentAutoSizingMultiplier = props.contentAutoSizingMultiplier
  else
    -- Try to source from theme
-    local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+    local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
    if themeToUse then
      -- First check if themeComponent has a multiplier
      if self.themeComponent then
@@ -412,7 +453,7 @@ function Element.new(props)
    self.fontFamily = self.parent.fontFamily
  elseif props.themeComponent then
    -- If using themeComponent, try to get default from theme
-    local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+    local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
    if themeToUse and themeToUse.fonts and themeToUse.fonts["default"] then
      self.fontFamily = "default"
    else
@@ -572,7 +613,7 @@ function Element.new(props)
  local use9PatchPadding = false
  local ninePatchContentPadding = nil
  if self.themeComponent then
-    local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+    local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
    if themeToUse and themeToUse.components[self.themeComponent] then
      local component = themeToUse.components[self.themeComponent]
      if component._ninePatchData and component._ninePatchData.contentPadding then
@@ -602,7 +643,7 @@ function Element.new(props)
    -- Scale 9-patch content padding to match the actual rendered size
    -- The contentPadding values are in the original image's pixel coordinates,
    -- but we need to scale them proportionally to the element's actual size
-    local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+    local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
    if themeToUse and themeToUse.components[self.themeComponent] then
      local component = themeToUse.components[self.themeComponent]
      local atlasImage = component._loadedAtlas or themeToUse.atlas
@@ -825,7 +866,7 @@ function Element.new(props)
      self.textColor = props.textColor
    else
      -- Try to get text color from theme
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.colors and themeToUse.colors.text then
        self.textColor = themeToUse.colors.text
      else
@@ -956,7 +997,7 @@ function Element.new(props)
      self.textColor = self.parent.textColor
    else
      -- Try to get text color from theme
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.colors and themeToUse.colors.text then
        self.textColor = themeToUse.colors.text
      else
@@ -1620,7 +1661,7 @@ function Element:getScaledContentPadding()
    return nil
  end

-  local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+  local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
  if not themeToUse or not themeToUse.components[self.themeComponent] then
    return nil
  end
@@ -2330,14 +2371,14 @@ function Element:draw(backdropCanvas)
    local themeToUse = nil
    if self.theme then
      -- Element specifies a specific theme - load it if needed
-      if themes[self.theme] then
-        themeToUse = themes[self.theme]
+      if Theme.get(self.theme) then
+        themeToUse = Theme.get(self.theme)
      else
        -- Try to load the theme
        pcall(function()
          Theme.load(self.theme)
        end)
-        themeToUse = themes[self.theme]
+        themeToUse = Theme.get(self.theme)
      end
    else
      -- Use active theme
@@ -2423,7 +2464,7 @@ function Element:draw(backdropCanvas)
      local fontPath = nil
      if self.fontFamily then
        -- Check if fontFamily is a theme font name
-        local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+        local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
        if themeToUse and themeToUse.fonts and themeToUse.fonts[self.fontFamily] then
          fontPath = themeToUse.fonts[self.fontFamily]
        else
@@ -2432,7 +2473,7 @@ function Element:draw(backdropCanvas)
        end
      elseif self.themeComponent then
        -- If using themeComponent but no fontFamily specified, check for default font in theme
-        local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+        local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
        if themeToUse and themeToUse.fonts and themeToUse.fonts.default then
          fontPath = themeToUse.fonts.default
        end
@@ -3221,14 +3262,14 @@ function Element:calculateTextWidth()
    -- Resolve font path from font family (same logic as in draw)
    local fontPath = nil
    if self.fontFamily then
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.fonts and themeToUse.fonts[self.fontFamily] then
        fontPath = themeToUse.fonts[self.fontFamily]
      else
        fontPath = self.fontFamily
      end
    elseif self.themeComponent then
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.fonts and themeToUse.fonts.default then
        fontPath = themeToUse.fonts.default
      end
@@ -3264,14 +3305,14 @@ function Element:calculateTextHeight()
    -- Resolve font path from font family (same logic as in draw)
    local fontPath = nil
    if self.fontFamily then
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.fonts and themeToUse.fonts[self.fontFamily] then
        fontPath = themeToUse.fonts[self.fontFamily]
      else
        fontPath = self.fontFamily
      end
    elseif self.themeComponent then
-      local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+      local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
      if themeToUse and themeToUse.fonts and themeToUse.fonts.default then
        fontPath = themeToUse.fonts.default
      end
@@ -3917,7 +3958,7 @@ function Element:_getFont()
  -- Get font path from theme or element
  local fontPath = nil
  if self.fontFamily then
-    local themeToUse = self.theme and themes[self.theme] or Theme.getActive()
+    local themeToUse = self.theme and Theme.get(self.theme) or Theme.getActive()
    if themeToUse and themeToUse.fonts and themeToUse.fonts[self.fontFamily] then
      fontPath = themeToUse.fonts[self.fontFamily]
    else
--- a/flexlove/Grid.lua
+++ b/flexlove/Grid.lua
@@ -0,0 +1,136 @@
+-- ====================
+-- Grid Layout System
+-- ====================
+
+local modulePath = (...):match("(.-)[^%.]+$")
+local utils = require(modulePath .. "utils")
+local enums = utils.enums
+
+local Positioning = enums.Positioning
+local AlignItems = enums.AlignItems
+
+--- Simple grid layout calculations
+local Grid = {}
+
+--- Layout grid items within a grid container using simple row/column counts
+---@param element Element -- Grid container element
+function Grid.layoutGridItems(element)
+  local rows = element.gridRows or 1
+  local columns = element.gridColumns or 1
+
+  -- Calculate space reserved by absolutely positioned siblings
+  local reservedLeft = 0
+  local reservedRight = 0
+  local reservedTop = 0
+  local reservedBottom = 0
+
+  for _, child in ipairs(element.children) do
+    -- Only consider absolutely positioned children with explicit positioning
+    if child.positioning == Positioning.ABSOLUTE and child._explicitlyAbsolute then
+      -- BORDER-BOX MODEL: Use border-box dimensions for space calculations
+      local childBorderBoxWidth = child:getBorderBoxWidth()
+      local childBorderBoxHeight = child:getBorderBoxHeight()
+
+      if child.left then
+        reservedLeft = math.max(reservedLeft, child.left + childBorderBoxWidth)
+      end
+      if child.right then
+        reservedRight = math.max(reservedRight, child.right + childBorderBoxWidth)
+      end
+      if child.top then
+        reservedTop = math.max(reservedTop, child.top + childBorderBoxHeight)
+      end
+      if child.bottom then
+        reservedBottom = math.max(reservedBottom, child.bottom + childBorderBoxHeight)
+      end
+    end
+  end
+
+  -- Calculate available space (accounting for padding and reserved space)
+  -- BORDER-BOX MODEL: element.width and element.height are already content dimensions
+  local availableWidth = element.width - reservedLeft - reservedRight
+  local availableHeight = element.height - reservedTop - reservedBottom
+
+  -- Get gaps
+  local columnGap = element.columnGap or 0
+  local rowGap = element.rowGap or 0
+
+  -- Calculate cell sizes (equal distribution)
+  local totalColumnGaps = (columns - 1) * columnGap
+  local totalRowGaps = (rows - 1) * rowGap
+  local cellWidth = (availableWidth - totalColumnGaps) / columns
+  local cellHeight = (availableHeight - totalRowGaps) / rows
+
+  -- Get children that participate in grid layout
+  local gridChildren = {}
+  for _, child in ipairs(element.children) do
+    if not (child.positioning == Positioning.ABSOLUTE and child._explicitlyAbsolute) then
+      table.insert(gridChildren, child)
+    end
+  end
+
+  -- Place children in grid cells
+  for i, child in ipairs(gridChildren) do
+    -- Calculate row and column (0-indexed for calculation)
+    local index = i - 1
+    local col = index % columns
+    local row = math.floor(index / columns)
+
+    -- Skip if we've exceeded the grid
+    if row >= rows then
+      break
+    end
+
+    -- Calculate cell position (accounting for reserved space)
+    local cellX = element.x + element.padding.left + reservedLeft + (col * (cellWidth + columnGap))
+    local cellY = element.y + element.padding.top + reservedTop + (row * (cellHeight + rowGap))
+
+    -- Apply alignment within grid cell (default to stretch)
+    local effectiveAlignItems = element.alignItems or AlignItems.STRETCH
+
+    -- Stretch child to fill cell by default
+    -- BORDER-BOX MODEL: Set border-box dimensions, content area adjusts automatically
+    if effectiveAlignItems == AlignItems.STRETCH or effectiveAlignItems == "stretch" then
+      child.x = cellX
+      child.y = cellY
+      child._borderBoxWidth = cellWidth
+      child._borderBoxHeight = cellHeight
+      child.width = math.max(0, cellWidth - child.padding.left - child.padding.right)
+      child.height = math.max(0, cellHeight - child.padding.top - child.padding.bottom)
+      -- Disable auto-sizing when stretched by grid
+      child.autosizing.width = false
+      child.autosizing.height = false
+    elseif effectiveAlignItems == AlignItems.CENTER or effectiveAlignItems == "center" then
+      local childBorderBoxWidth = child:getBorderBoxWidth()
+      local childBorderBoxHeight = child:getBorderBoxHeight()
+      child.x = cellX + (cellWidth - childBorderBoxWidth) / 2
+      child.y = cellY + (cellHeight - childBorderBoxHeight) / 2
+    elseif effectiveAlignItems == AlignItems.FLEX_START or effectiveAlignItems == "flex-start" or effectiveAlignItems == "start" then
+      child.x = cellX
+      child.y = cellY
+    elseif effectiveAlignItems == AlignItems.FLEX_END or effectiveAlignItems == "flex-end" or effectiveAlignItems == "end" then
+      local childBorderBoxWidth = child:getBorderBoxWidth()
+      local childBorderBoxHeight = child:getBorderBoxHeight()
+      child.x = cellX + cellWidth - childBorderBoxWidth
+      child.y = cellY + cellHeight - childBorderBoxHeight
+    else
+      -- Default to stretch
+      child.x = cellX
+      child.y = cellY
+      child._borderBoxWidth = cellWidth
+      child._borderBoxHeight = cellHeight
+      child.width = math.max(0, cellWidth - child.padding.left - child.padding.right)
+      child.height = math.max(0, cellHeight - child.padding.top - child.padding.bottom)
+      -- Disable auto-sizing when stretched by grid
+      child.autosizing.width = false
+      child.autosizing.height = false
+    end
+
+    -- Layout child's children if it has any
+    if #child.children > 0 then
+      child:layoutChildren()
+    end
+  end
+end
+
+return Grid
--- a/flexlove/GuiState.lua
+++ b/flexlove/GuiState.lua
@@ -0,0 +1,36 @@
+-- ====================
+-- GUI State Module
+-- ====================
+-- Shared state between Gui and Element to avoid circular dependencies
+
+---@class GuiState
+local GuiState = {
+  -- Top-level elements
+  topElements = {},
+  
+  -- Base scale configuration
+  baseScale = nil, -- {width: number, height: number}
+  
+  -- Current scale factors
+  scaleFactors = { x = 1.0, y = 1.0 },
+  
+  -- Default theme name
+  defaultTheme = nil,
+  
+  -- Currently focused element (for keyboard input)
+  _focusedElement = nil,
+  
+  -- Active event element (for current frame)
+  _activeEventElement = nil,
+  
+  -- Cached viewport dimensions
+  _cachedViewport = { width = 0, height = 0 },
+}
+
+--- Get current scale factors
+---@return number, number -- scaleX, scaleY
+function GuiState.getScaleFactors()
+  return GuiState.scaleFactors.x, GuiState.scaleFactors.y
+end
+
+return GuiState
--- a/flexlove/InputEvent.lua
+++ b/flexlove/InputEvent.lua
@@ -0,0 +1,46 @@
+-- ====================
+-- Input Event System
+-- ====================
+
+---@class InputEvent
+---@field type "click"|"press"|"release"|"rightclick"|"middleclick"|"drag"
+---@field button number -- Mouse button: 1 (left), 2 (right), 3 (middle)
+---@field x number -- Mouse X position
+---@field y number -- Mouse Y position
+---@field dx number? -- Delta X from drag start (only for drag events)
+---@field dy number? -- Delta Y from drag start (only for drag events)
+---@field modifiers {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
+---@field clickCount number -- Number of clicks (for double/triple click detection)
+---@field timestamp number -- Time when event occurred
+local InputEvent = {}
+InputEvent.__index = InputEvent
+
+---@class InputEventProps
+---@field type "click"|"press"|"release"|"rightclick"|"middleclick"|"drag"
+---@field button number
+---@field x number
+---@field y number
+---@field dx number?
+---@field dy number?
+---@field modifiers {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
+---@field clickCount number?
+---@field timestamp number?
+
+--- Create a new input event
+---@param props InputEventProps
+---@return InputEvent
+function InputEvent.new(props)
+  local self = setmetatable({}, InputEvent)
+  self.type = props.type
+  self.button = props.button
+  self.x = props.x
+  self.y = props.y
+  self.dx = props.dx
+  self.dy = props.dy
+  self.modifiers = props.modifiers
+  self.clickCount = props.clickCount or 1
+  self.timestamp = props.timestamp or love.timer.getTime()
+  return self
+end
+
+return InputEvent
--- a/flexlove/NineSlice.lua
+++ b/flexlove/NineSlice.lua
@@ -4,7 +4,8 @@ Handles rendering of 9-patch components with Android-style scaling.
 Corners can be scaled independently while edges stretch in one dimension.
 ]]

-local ImageScaler = require("flexlove.ImageScaler")
+local modulePath = (...):match("(.-)[^%.]+$")
+local ImageScaler = require(modulePath .. "ImageScaler")

 --- Standardized error message formatter
 ---@param module string -- Module name (e.g., "Color", "Theme", "Units")
--- a/flexlove/Theme.lua
+++ b/flexlove/Theme.lua
@@ -4,9 +4,11 @@ Manages theme loading, registration, and component/color/font access.
 Supports 9-patch images, component states, and dynamic theme switching.
 ]]

-local Color = require("flexlove.Color")
-local NinePatchParser = require("flexlove.NinePatchParser")
-local ImageScaler = require("flexlove.ImageScaler")
+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")
@@ -490,4 +492,11 @@ function Theme.getColorOrDefault(colorName, fallback)
  return fallback or Color.new(1, 1, 1, 1)
 end

+--- Get a theme by name
+---@param themeName string -- Name of the theme
+---@return Theme|nil -- Returns theme or nil if not found
+function Theme.get(themeName)
+  return themes[themeName]
+end
+
 return Theme
--- a/flexlove/constants.lua
+++ b/flexlove/constants.lua
@@ -13,4 +13,6 @@ local TEXT_SIZE_PRESETS = {
  ["4xl"] = 7.0, -- 7vh
 }

-return { TEXT_SIZE_PRESETS }
+return {
+  TEXT_SIZE_PRESETS = TEXT_SIZE_PRESETS
+}
--- a/flexlove/utils.lua
+++ b/flexlove/utils.lua
@@ -66,91 +66,6 @@ local enums = {
  },
 }

---@class ElementProps
---@field id string?
---@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?
---@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: 10)
---@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 children (default: {top=0, right=0, bottom=0, left=0})
---@field text string? -- Text content to display (default: nil)
---@field titleColor Color? -- Color of the text content (default: black)
---@field textAlign TextAlign? -- Alignment of the text content (default: START)
---@field textColor Color? -- Color of the text content (default: black)
---@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")
---@field minTextSize number?
---@field maxTextSize number?
---@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default)
---@field autoScaleText boolean? -- Whether text should auto-scale with window size (default: true)
---@field positioning Positioning? -- Layout positioning mode (default: RELATIVE)
---@field flexDirection FlexDirection? -- Direction of flex layout (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 (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 callback fun(element:Element, event:InputEvent)? -- Callback function for interaction events
---@field transform table? -- Transform properties for animations and styling
---@field transition table? -- 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
---@field rowGap number|string? -- Gap between grid rows
---@field theme string? -- Theme name to use (e.g., "space", "dark"). 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)
---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme)
---@field scaleCorners number? -- Scale multiplier for 9-slice corners/edges. E.g., 2 = 2x size (overrides theme setting)
---@field scalingAlgorithm "nearest"|"bilinear"? -- Scaling algorithm for 9-slice 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)
---@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)
---@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: "visible")
---@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
---@field scrollbarTrackColor Color? -- Scrollbar track color
---@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)
-
---@class Border
---@field top boolean?
---@field right boolean?
---@field bottom boolean?
---@field left boolean?
-
 --- Get current keyboard modifiers state
 ---@return {shift:boolean, ctrl:boolean, alt:boolean, super:boolean}
 local function getModifiers()
@@ -164,72 +79,94 @@ local function getModifiers()
 end

 local TEXT_SIZE_PRESETS = {
-  ["2xs"] = 0.75, -- 0.75vh
-  xxs = 0.75, -- 0.75vh
-  xs = 1.25, -- 1.25vh
-  sm = 1.75, -- 1.75vh
-  md = 2.25, -- 2.25vh (default)
-  lg = 2.75, -- 2.75vh
-  xl = 3.5, -- 3.5vh
-  xxl = 4.5, -- 4.5vh
-  ["2xl"] = 4.5, -- 4.5vh
-  ["3xl"] = 5.0, -- 5vh
-  ["4xl"] = 7.0, -- 7vh
+  ["2xs"] = 0.75,
+  xxs = 0.75,
+  xs = 1.25,
+  sm = 1.75,
+  md = 2.25,
+  lg = 2.75,
+  xl = 3.5,
+  xxl = 4.5,
+  ["2xl"] = 4.5,
+  ["3xl"] = 5.0,
+  ["4xl"] = 7.0,
 }

-- ====================
-- Text Size Utilities
-- ====================
-
 --- Resolve text size preset to viewport units
 ---@param sizeValue string|number
---@return number?, string? -- Returns value and unit ("vh" for presets, original unit otherwise)
+---@return number?, string?
 local function resolveTextSizePreset(sizeValue)
  if type(sizeValue) == "string" then
-    -- Check if it's a preset
    local preset = TEXT_SIZE_PRESETS[sizeValue]
    if preset then
      return preset, "vh"
    end
  end
-  -- Not a preset, return nil to indicate normal parsing should occur
  return nil, nil
 end

+
+--- Auto-detect the base path where FlexLove is located
+---@return string filesystemPath
+local function getFlexLoveBasePath()
+  local info = debug.getinfo(1, "S")
+  if info and info.source then
+    local source = info.source
+    if source:sub(1, 1) == "@" then
+      source = source:sub(2)
+    end
+
+    local filesystemPath = source:match("(.*/)")
+    if filesystemPath then
+      local fsPath = filesystemPath
+      fsPath = fsPath:gsub("^%./", "")
+      fsPath = fsPath:gsub("/$", "")
+      fsPath = fsPath:gsub("/flexlove$", "")
+      return fsPath
+    end
+  end
+  return "libs"
+end
+
+local FLEXLOVE_FILESYSTEM_PATH = getFlexLoveBasePath()
+
+--- Helper function to resolve paths relative to FlexLove
+---@param path string
+---@return string
+local function resolveImagePath(path)
+  if path:match("^/") or path:match("^[A-Z]:") then
+    return path
+  end
+  return FLEXLOVE_FILESYSTEM_PATH .. "/" .. path
+end
+
 local FONT_CACHE = {}
-local FONT_CACHE_MAX_SIZE = 50 -- Limit cache size to prevent unbounded growth
-local FONT_CACHE_ORDER = {} -- Track access order for LRU eviction
+local FONT_CACHE_MAX_SIZE = 50
+local FONT_CACHE_ORDER = {}

 --- Create or get a font from cache
 ---@param size number
---@param fontPath string? -- Optional: path to font file
+---@param fontPath string?
 ---@return love.Font
 function FONT_CACHE.get(size, fontPath)
-  -- Create cache key from size and font path
  local cacheKey = fontPath and (fontPath .. "_" .. tostring(size)) or tostring(size)

  if not FONT_CACHE[cacheKey] then
    if fontPath then
-      -- Load custom font
      local resolvedPath = resolveImagePath(fontPath)
-      -- Note: love.graphics.newFont signature is (path, size) for custom fonts
      local success, font = pcall(love.graphics.newFont, resolvedPath, size)
      if success then
        FONT_CACHE[cacheKey] = font
      else
-        -- Fallback to default font if custom font fails to load
        print("[FlexLove] Failed to load font: " .. fontPath .. " - using default font")
        FONT_CACHE[cacheKey] = love.graphics.newFont(size)
      end
    else
-      -- Load default font
      FONT_CACHE[cacheKey] = love.graphics.newFont(size)
    end

-    -- Add to access order for LRU tracking
    table.insert(FONT_CACHE_ORDER, cacheKey)

-    -- Evict oldest entry if cache is full (LRU eviction)
    if #FONT_CACHE_ORDER > FONT_CACHE_MAX_SIZE then
      local oldestKey = table.remove(FONT_CACHE_ORDER, 1)
      FONT_CACHE[oldestKey] = nil
@@ -240,7 +177,7 @@ end

 --- Get font for text size (cached)
 ---@param textSize number?
---@param fontPath string? -- Optional: path to font file
+---@param fontPath string?
 ---@return love.Font
 function FONT_CACHE.getFont(textSize, fontPath)
  if textSize then
@@ -250,4 +187,9 @@ function FONT_CACHE.getFont(textSize, fontPath)
  end
 end

-return { enums, FONT_CACHE, resolveTextSizePreset, getModifiers }
+return {
+  enums = enums,
+  FONT_CACHE = FONT_CACHE,
+  resolveTextSizePreset = resolveTextSizePreset,
+  getModifiers = getModifiers,
+}