fix scrollbar spacing issue

modules/Element.lua

@@ -140,6 +140,7 @@
 ---@field invertScroll boolean? -- Invert mouse wheel scroll direction (default: false)
 ---@field scrollBarStyle string? -- Scrollbar style name from theme (selects from theme.scrollbars)
 ---@field scrollbarKnobOffset number|table? -- Scrollbar knob/handle offset (number or {x, y} or {horizontal, vertical})
+---@field scrollbarPlacement string? -- "reserve-space"|"overlay" -- Whether scrollbar reserves space or overlays content (default: "reserve-space")
 ---@field _overflowX boolean? -- Internal: whether content overflows horizontally
 ---@field _overflowY boolean? -- Internal: whether content overflows vertically
 ---@field _contentWidth number? -- Internal: total content width
@@ -1939,6 +1940,7 @@ function Element.new(props)
       scrollBarStyle = props.scrollBarStyle,
       scrollbarKnobOffset = props.scrollbarKnobOffset,
       hideScrollbars = props.hideScrollbars,
+      scrollbarPlacement = props.scrollbarPlacement,
       _scrollX = props._scrollX,
       _scrollY = props._scrollY,
     }, scrollManagerDeps)
@@ -1957,6 +1959,7 @@ function Element.new(props)
     self.scrollBarStyle = self._scrollManager.scrollBarStyle
     self.scrollbarKnobOffset = self._scrollManager.scrollbarKnobOffset
     self.hideScrollbars = self._scrollManager.hideScrollbars
+    self.scrollbarPlacement = self._scrollManager.scrollbarPlacement
 
     -- Initialize state properties (will be synced from ScrollManager)
     self._overflowX = false

modules/LayoutEngine.lua

@@ -445,12 +445,48 @@ function LayoutEngine:layoutChildren()
   -- BORDER-BOX MODEL: element.width and element.height are already content dimensions (padding subtracted)
   local availableMainSize = 0
   local availableCrossSize = 0
+  
+  -- Reserve space for scrollbars if needed (reserve-space mode)
+  local scrollbarReservedWidth = 0
+  local scrollbarReservedHeight = 0
+  if self.element._scrollManager and self.element._scrollManager.scrollbarPlacement == "reserve-space" then
+    scrollbarReservedWidth, scrollbarReservedHeight = self.element._scrollManager:getReservedSpace(self.element)
+  end
+  
   if self.flexDirection == self._FlexDirection.HORIZONTAL then
-    availableMainSize = self.element.width
-    availableCrossSize = self.element.height
+    availableMainSize = self.element.width - scrollbarReservedWidth
+    availableCrossSize = self.element.height - scrollbarReservedHeight
   else
-    availableMainSize = self.element.height
-    availableCrossSize = self.element.width
+    availableMainSize = self.element.height - scrollbarReservedHeight
+    availableCrossSize = self.element.width - scrollbarReservedWidth
+  end
+
+  -- Adjust children with percentage-based cross-axis dimensions when scrollbar space is reserved
+  if (scrollbarReservedWidth > 0 or scrollbarReservedHeight > 0) then
+    local isHorizontal = self.flexDirection == self._FlexDirection.HORIZONTAL
+    for _, child in ipairs(flexChildren) do
+      if isHorizontal then
+        -- Horizontal flex: cross-axis is height
+        if child.units and child.units.height and child.units.height.unit == "%" then
+          -- Re-resolve percentage height against reduced cross-axis size
+          -- The percentage applies to border-box, so we need to subtract padding to get content height
+          local newBorderBoxHeight = (child.units.height.value / 100) * availableCrossSize
+          local newHeight = math.max(0, newBorderBoxHeight - child.padding.top - child.padding.bottom)
+          child.height = newHeight
+          child._borderBoxHeight = newBorderBoxHeight
+        end
+      else
+        -- Vertical flex: cross-axis is width
+        if child.units and child.units.width and child.units.width.unit == "%" then
+          -- Re-resolve percentage width against reduced cross-axis size
+          -- The percentage applies to border-box, so we need to subtract padding to get content width
+          local newBorderBoxWidth = (child.units.width.value / 100) * availableCrossSize
+          local newWidth = math.max(0, newBorderBoxWidth - child.padding.left - child.padding.right)
+          child.width = newWidth
+          child._borderBoxWidth = newBorderBoxWidth
+        end
+      end
+    end
   end
 
   -- Handle flex wrap: create lines of children

modules/ScrollManager.lua

@@ -12,6 +12,7 @@
 ---@field scrollBarStyle string? -- Scrollbar style name from theme (selects from theme.scrollbars)
 ---@field scrollbarKnobOffset table -- {x: number, y: number, horizontal: number, vertical: number} -- Offset for scrollbar knob/handle position
 ---@field hideScrollbars table -- {vertical: boolean, horizontal: boolean}
+---@field scrollbarPlacement string -- "reserve-space"|"overlay" -- Whether scrollbar reserves space or overlays content (default: "reserve-space")
 ---@field touchScrollEnabled boolean -- Enable touch scrolling
 ---@field momentumScrollEnabled boolean -- Enable momentum scrolling
 ---@field bounceEnabled boolean -- Enable bounce effects at boundaries
@@ -98,6 +99,9 @@ function ScrollManager.new(config, deps)
   -- hideScrollbars can be boolean or table {vertical: boolean, horizontal: boolean}
   self.hideScrollbars = self._utils.normalizeBooleanTable(config.hideScrollbars, false)
 
+  -- Scrollbar placement: "reserve-space" (default) or "overlay"
+  self.scrollbarPlacement = config.scrollbarPlacement or "reserve-space"
+
   -- Touch scrolling configuration
   self.touchScrollEnabled = config.touchScrollEnabled ~= false -- Default true
   self.momentumScrollEnabled = config.momentumScrollEnabled ~= false -- Default true
@@ -146,6 +150,34 @@ function ScrollManager.new(config, deps)
   return self
 end
 
+--- Get the space reserved for scrollbars (width and height reduction)
+--- This is called BEFORE layout to reduce available space for children
+---@param element Element The parent Element instance
+---@return number reservedWidth, number reservedHeight
+function ScrollManager:getReservedSpace(element)
+  if self.scrollbarPlacement ~= "reserve-space" then
+    return 0, 0
+  end
+
+  local overflowX = self.overflowX or self.overflow
+  local overflowY = self.overflowY or self.overflow
+  
+  local reservedWidth = 0
+  local reservedHeight = 0
+
+  -- Reserve space for vertical scrollbar if overflow mode requires it
+  if (overflowY == "scroll" or overflowY == "auto") and not self.hideScrollbars.vertical then
+    reservedWidth = self.scrollbarWidth + (self.scrollbarPadding * 2)
+  end
+
+  -- Reserve space for horizontal scrollbar if overflow mode requires it
+  if (overflowX == "scroll" or overflowX == "auto") and not self.hideScrollbars.horizontal then
+    reservedHeight = self.scrollbarWidth + (self.scrollbarPadding * 2)
+  end
+
+  return reservedWidth, reservedHeight
+end
+
 --- Detect if content overflows container bounds
 ---@param element Element The parent Element instance
 function ScrollManager:detectOverflow(element)
@@ -199,6 +231,14 @@ function ScrollManager:detectOverflow(element)
   local containerWidth = element.width - element.padding.left - element.padding.right
   local containerHeight = element.height - element.padding.top - element.padding.bottom
 
+  -- If scrollbarPlacement is "reserve-space", we need to subtract the reserved space
+  -- because the layout already accounted for it, but element.width/height are still full size
+  if self.scrollbarPlacement == "reserve-space" then
+    local reservedWidth, reservedHeight = self:getReservedSpace()
+    containerWidth = containerWidth - reservedWidth
+    containerHeight = containerHeight - reservedHeight
+  end
+
   self._overflowX = self._contentWidth > containerWidth
   self._overflowY = self._contentHeight > containerHeight
 
@@ -674,6 +714,7 @@ function ScrollManager:getState()
     _scrollbarHoveredHorizontal = self._scrollbarHoveredHorizontal or false,
     scrollBarStyle = self.scrollBarStyle,
     scrollbarKnobOffset = self.scrollbarKnobOffset,
+    scrollbarPlacement = self.scrollbarPlacement,
     _overflowX = self._overflowX,
     _overflowY = self._overflowY,
     _contentWidth = self._contentWidth,
@@ -752,6 +793,10 @@ function ScrollManager:setState(state)
     self.scrollbarKnobOffset = self._utils.normalizeOffsetTable(state.scrollbarKnobOffset, 0)
   end
 
+  if state.scrollbarPlacement ~= nil then
+    self.scrollbarPlacement = state.scrollbarPlacement
+  end
+
   if state._overflowX ~= nil then
     self._overflowX = state._overflowX
   end

modules/types.lua

@@ -67,6 +67,10 @@ local AnimationProps = {}
 ---@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 flex number|string? -- Shorthand for flexGrow, flexShrink, flexBasis: number (flex-grow only), string ("1 0 auto"), or nil (default: nil)
+---@field flexGrow number? -- How much the element should grow relative to siblings (default: 0)
+---@field flexShrink number? -- How much the element should shrink relative to siblings (default: 1)
+---@field flexBasis number|string|CalcObject? -- Initial size before growing/shrinking: number (px), string ("50%", "10vw", "auto"), or CalcObject (default: "auto")
 ---@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
@@ -126,6 +130,7 @@ local AnimationProps = {}
 ---@field smoothScrollEnabled boolean? -- Enable smooth scrolling animation for wheel events (default: false)
 ---@field scrollBarStyle string? -- Scrollbar style name from theme (selects from theme.scrollbars, default: uses first scrollbar or fallback rendering)
 ---@field scrollbarKnobOffset number|{x:number, y:number}|{horizontal:number, vertical:number}? -- Offset for scrollbar knob/handle position in pixels (number for both axes, or table for per-axis control, default: 0, adds to theme offset)
+---@field scrollbarPlacement "reserve-space"|"overlay"? -- Scrollbar rendering mode: "reserve-space" (reduces content area, default) or "overlay" (renders over content)
 ---@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