calc module

modules/Units.lua

@@ -3,29 +3,36 @@
 ---@class Units
 ---@field _Context table? Context module dependency
 ---@field _ErrorHandler table? ErrorHandler module dependency
+---@field _Calc table? Calc module dependency
 local Units = {}
 
 --- Initialize Units module with dependencies
----@param deps table Dependencies: { Context = table?, ErrorHandler = table? }
+---@param deps table Dependencies: { Context = table?, ErrorHandler = table?, Calc = table? }
 function Units.init(deps)
   Units._Context = deps.Context
   Units._ErrorHandler = deps.ErrorHandler
+  Units._Calc = deps.Calc
 end
 
 --- Parse a unit value into numeric value and unit type
---- Supports: px (pixels), % (percentage), vw/vh (viewport), ew/eh (element)
----@param value string|number The value to parse (e.g., "50px", "10%", "2vw", 100)
----@return number numericValue The numeric portion of the value
----@return string unitType The unit type ("px", "%", "vw", "vh", "ew", "eh")
+--- Supports: px (pixels), % (percentage), vw/vh (viewport), ew/eh (element), and calc() expressions
+---@param value string|number|table The value to parse (e.g., "50px", "10%", "2vw", 100, or calc object)
+---@return number|table numericValue The numeric portion of the value or calc object
+---@return string unitType The unit type ("px", "%", "vw", "vh", "ew", "eh", "calc")
 function Units.parse(value)
+  -- Check if value is a calc expression
+  if Units._Calc and Units._Calc.isCalc(value) then
+    return value, "calc"
+  end
+
   if type(value) == "number" then
     return value, "px"
   end
 
-  if type(value) ~= "string" then
+  if type(value) ~= "string" and type(value) ~= "table" then
     Units._ErrorHandler:warn("Units", "VAL_001", {
       property = "unit value",
-      expected = "string or number",
+      expected = "string, number, or calc object",
       got = type(value),
     })
     return 0, "px"
@@ -87,15 +94,28 @@ function Units.parse(value)
 end
 
 --- Convert relative units to absolute pixel values
---- Resolves %, vw, vh units based on viewport and parent dimensions
----@param value number Numeric value to convert
----@param unit string Unit type ("px", "%", "vw", "vh", "ew", "eh")
+--- Resolves %, vw, vh units based on viewport and parent dimensions, and evaluates calc() expressions
+---@param value number|table Numeric value to convert or calc object
+---@param unit string Unit type ("px", "%", "vw", "vh", "ew", "eh", "calc")
 ---@param viewportWidth number Current viewport width in pixels
 ---@param viewportHeight number Current viewport height in pixels
 ---@param parentSize number? Required for percentage units (parent dimension in pixels)
+---@param elementWidth number? Required for ew units in calc expressions (element width in pixels)
+---@param elementHeight number? Required for eh units in calc expressions (element height in pixels)
 ---@return number resolvedValue Resolved pixel value
-function Units.resolve(value, unit, viewportWidth, viewportHeight, parentSize)
-  if unit == "px" then
+function Units.resolve(value, unit, viewportWidth, viewportHeight, parentSize, elementWidth, elementHeight)
+  if unit == "calc" then
+    -- Resolve calc expression
+    if Units._Calc then
+      return Units._Calc.resolve(value, viewportWidth, viewportHeight, parentSize, elementWidth, elementHeight)
+    else
+      Units._ErrorHandler:warn("Units", "VAL_006", {
+        unit = "calc",
+        issue = "Calc module not available",
+      })
+      return 0
+    end
+  elseif unit == "px" then
     return value
   elseif unit == "%" then
     if not parentSize then
@@ -113,7 +133,7 @@ function Units.resolve(value, unit, viewportWidth, viewportHeight, parentSize)
   else
     Units._ErrorHandler:warn("Units", "VAL_005", {
       unit = unit,
-      validUnits = "px, %, vw, vh, ew, eh",
+      validUnits = "px, %, vw, vh, ew, eh, calc",
     })
     return 0
   end
@@ -169,26 +189,26 @@ function Units.resolveSpacing(spacingProps, parentWidth, parentHeight)
   local horizontal = spacingProps.horizontal
 
   if vertical then
-    if type(vertical) == "string" then
+    if type(vertical) == "string" or (Units._Calc and Units._Calc.isCalc(vertical)) then
       local value, unit = Units.parse(vertical)
-      vertical = Units.resolve(value, unit, viewportWidth, viewportHeight, parentHeight)
+      vertical = Units.resolve(value, unit, viewportWidth, viewportHeight, parentHeight, nil, nil)
     end
   end
 
   if horizontal then
-    if type(horizontal) == "string" then
+    if type(horizontal) == "string" or (Units._Calc and Units._Calc.isCalc(horizontal)) then
       local value, unit = Units.parse(horizontal)
-      horizontal = Units.resolve(value, unit, viewportWidth, viewportHeight, parentWidth)
+      horizontal = Units.resolve(value, unit, viewportWidth, viewportHeight, parentWidth, nil, nil)
     end
   end
 
   for _, side in ipairs({ "top", "right", "bottom", "left" }) do
     local value = spacingProps[side]
     if value then
-      if type(value) == "string" then
+      if type(value) == "string" or (Units._Calc and Units._Calc.isCalc(value)) then
         local numValue, unit = Units.parse(value)
         local parentSize = (side == "top" or side == "bottom") and parentHeight or parentWidth
-        result[side] = Units.resolve(numValue, unit, viewportWidth, viewportHeight, parentSize)
+        result[side] = Units.resolve(numValue, unit, viewportWidth, viewportHeight, parentSize, nil, nil)
       else
         result[side] = value
       end
@@ -205,10 +225,15 @@ function Units.resolveSpacing(spacingProps, parentWidth, parentHeight)
 end
 
 --- Validate a unit string format
---- Checks if the string can be successfully parsed as a valid unit
----@param unitStr string The unit string to validate (e.g., "50px", "10%")
+--- Checks if the string can be successfully parsed as a valid unit or calc expression
+---@param unitStr string|table The unit string to validate (e.g., "50px", "10%") or calc object
 ---@return boolean isValid True if the unit string is valid, false otherwise
 function Units.isValid(unitStr)
+  -- Check if it's a calc expression
+  if Units._Calc and Units._Calc.isCalc(unitStr) then
+    return true
+  end
+
   if type(unitStr) ~= "string" then
     return false
   end