Refactor documentation and examples for Display, Frame, Program, SideNav, TabControl, and Tree elements

Author: NoryiE

src/elements/Display.lua

@@ -6,13 +6,7 @@ local colorHex = require("libraries/colorHex")
 ---@configDescription The Display is a special element which uses the CC Window API which you can use.
 ---@configDefault false
 
---- A specialized element that provides direct access to ComputerCraft's Window API. 
---- It acts as a canvas where you can use standard CC terminal operations, making it ideal for:
---- - Integration with existing CC programs and APIs
---- - Custom drawing operations
---- - Terminal emulation
---- - Complex text manipulation
---- The Display maintains its own terminal buffer and can be manipulated using familiar CC terminal methods.
+--- A specialized element that provides direct access to ComputerCraft's Window API. It acts as a canvas where you can use standard CC terminal operations.
 --- @usage [[
 --- -- Create a display for a custom terminal
 --- local display = main:addDisplay()

src/elements/Frame.lua

@@ -117,18 +117,15 @@ end
 --- @return boolean handled Whether the event was handled
 --- @protected
 function Frame:mouse_drag(button, x, y)
-    if self:hasState("clicked") and self.dragging then
+    if self.dragging then
         local newX = x - self.dragStartX
         local newY = y - self.dragStartY
 
         self.set("x", newX)
         self.set("y", newY)
         return true
     end
-    if not self.dragging then
-        return Container.mouse_drag(self, button, x, y)
-    end
-    return false
+    return Container.mouse_drag(self, button, x, y)
 end
 
 --- @shortDescription Calculates the total height of all children elements

src/elements/Program.lua

@@ -6,6 +6,60 @@ local errorManager = require("errorManager")
 
 --- This is the program class. It provides a program that runs in a window.
 ---@class Program : VisualElement
+---@run [[
+--- local basalt = require("basalt")
+--- 
+--- local main = basalt.getMainFrame()
+--- 
+--- local execPath = "rom/programs/fun/worm.lua"
+--- 
+--- local btn = main:addButton({
+---     x = 5,
+---     y = 2,
+---     width = 20,
+---     height = 3,
+---     text = "Run Worm",
+--- }):onClick(function()
+---     local frame = main:addFrame({
+---         x = 2,
+---         y = 2,
+---         width = 28,
+---         height = 10,
+---         title = "Worm Program",
+---         draggable = true,
+---     })
+---     :setDraggingMap({{x=1, y=1, width=27, height=1}})
+---     :onFocus(function(self)
+---         self:prioritize()
+---     end)
+---     local program = frame:addProgram({
+---         x = 1,
+---         y = 2,
+---         width = 28,
+---         height = 9,
+---     })
+---     program:execute(execPath)
+---     frame:addLabel({
+---         x = 2,
+---         y = 1,
+---         text = "Worm",
+---         foreground = colors.lightBlue
+---     })
+---     frame:addButton({
+---         x = frame.get("width"),
+---         y = 1,
+---         width = 1,
+---         height = 1,
+---         text = "X",
+---         background = colors.red,
+---         foreground = colors.white
+---     }):onClick(function()
+---         frame:destroy()
+---     end)
+--- end)
+--- 
+--- basalt.run()
+--- ]]
 local Program = setmetatable({}, VisualElement)
 Program.__index = Program
 

src/elements/SideNav.lua

@@ -5,6 +5,100 @@ local tHex = require("libraries/colorHex")
 ---@configDescription A SideNav element that provides sidebar navigation with multiple content areas.
 
 --- The SideNav is a container that provides sidebar navigation functionality
+--- @run [[
+--- local basalt = require("basalt")
+--- local main = basalt.getMainFrame()
+--- 
+--- -- Create a simple SideNav
+--- local sideNav = main:addSideNav({
+---     x = 1,
+---     y = 1,
+---     sidebarWidth = 12,
+---     width = 48
+--- })
+--- 
+--- -- Tab 1: Home
+--- local homeTab = sideNav:newTab("Home")
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "Welcome!",
+---     foreground = colors.yellow
+--- })
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 4,
+---     text = "This is a simple",
+---     foreground = colors.white
+--- })
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 5,
+---     text = "SideNav example.",
+---     foreground = colors.white
+--- })
+--- 
+--- -- Tab 2: Counter
+--- local counterTab = sideNav:newTab("Counter")
+--- 
+--- local counterLabel = counterTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "Count: 0",
+---     foreground = colors.lime
+--- })
+--- 
+--- local count = 0
+--- counterTab:addButton({
+---     x = 2,
+---     y = 4,
+---     width = 12,
+---     height = 3,
+---     text = "Click Me",
+---     background = colors.blue
+--- })
+--- :setBackgroundState("clicked", colors.lightBlue)
+--- :onClick(function()
+---     count = count + 1
+---     counterLabel:setText("Count: " .. count)
+--- end)
+--- 
+--- -- Tab 3: Info
+--- local infoTab = sideNav:newTab("Info")
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "SideNav Features:",
+---     foreground = colors.orange
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 4,
+---     text = "- Multiple tabs",
+---     foreground = colors.gray
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 5,
+---     text = "- Easy navigation",
+---     foreground = colors.gray
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 6,
+---     text = "- Content per tab",
+---     foreground = colors.gray
+--- })
+--- 
+--- basalt.run()
+--- ]]
 ---@class SideNav : Container
 local SideNav = setmetatable({}, Container)
 SideNav.__index = SideNav

src/elements/TabControl.lua

@@ -6,6 +6,101 @@ local log = require("log")
 ---@configDescription A TabControl element that provides tabbed interface with multiple content areas.
 
 --- The TabControl is a container that provides tabbed interface functionality
+--- @run [[
+--- local basalt = require("basalt")
+
+--- local main = basalt.getMainFrame()
+--- 
+--- -- Create a simple TabControl
+--- local tabControl = main:addTabControl({
+---     x = 2,
+---     y = 2,
+---     width = 46,
+---     height = 15,
+--- })
+--- 
+--- -- Tab 1: Home
+--- local homeTab = tabControl:newTab("Home")
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "Welcome!",
+---     foreground = colors.yellow
+--- })
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 4,
+---     text = "This is a TabControl",
+---     foreground = colors.white
+--- })
+--- 
+--- homeTab:addLabel({
+---     x = 2,
+---     y = 5,
+---     text = "example with tabs.",
+---     foreground = colors.white
+--- })
+--- 
+--- -- Tab 2: Counter
+--- local counterTab = tabControl:newTab("Counter")
+--- 
+--- local counterLabel = counterTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "Count: 0",
+---     foreground = colors.lime
+--- })
+--- 
+--- local count = 0
+--- counterTab:addButton({
+---     x = 2,
+---     y = 4,
+---     width = 12,
+---     height = 3,
+---     text = "Click Me",
+---     background = colors.blue
+--- })
+--- :setBackgroundState("clicked", colors.lightBlue)
+--- :onClick(function()
+---     count = count + 1
+---     counterLabel:setText("Count: " .. count)
+--- end)
+--- 
+--- -- Tab 3: Info
+--- local infoTab = tabControl:newTab("Info")
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 2,
+---     text = "TabControl Features:",
+---     foreground = colors.orange
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 4,
+---     text = "- Horizontal tabs",
+---     foreground = colors.gray
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 5,
+---     text = "- Easy navigation",
+---     foreground = colors.gray
+--- })
+--- 
+--- infoTab:addLabel({
+---     x = 2,
+---     y = 6,
+---     text = "- Content per tab",
+---     foreground = colors.gray
+--- })
+--- 
+--- basalt.run()
+--- ]]
 ---@class TabControl : Container
 local TabControl = setmetatable({}, Container)
 TabControl.__index = TabControl

src/elements/Tree.lua

@@ -18,7 +18,7 @@ end
 
 --- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed, with support for selection and scrolling.
 --- @run [[
---- local basaltg = require("basalt")
+--- local basalt = require("basalt")
 --- local main = basalt.getMainFrame()
 --- 
 --- local fileTree = main:addTree()