From 78712342510383c4fcd341ed914d093c054c5262 Mon Sep 17 00:00:00 2001
From: Robert Jelic <36573031+NoryiE@users.noreply.github.com>
Date: Thu, 30 Oct 2025 09:23:33 +0100
Subject: [PATCH] Refactor documentation and examples for Display, Frame,
 Program, SideNav, TabControl, and Tree elements

---
 src/elements/Display.lua    |  8 +---
 src/elements/Frame.lua      |  7 +--
 src/elements/Program.lua    | 54 +++++++++++++++++++++
 src/elements/SideNav.lua    | 94 ++++++++++++++++++++++++++++++++++++
 src/elements/TabControl.lua | 95 +++++++++++++++++++++++++++++++++++++
 src/elements/Tree.lua       |  2 +-
 6 files changed, 247 insertions(+), 13 deletions(-)

diff --git a/src/elements/Display.lua b/src/elements/Display.lua
index dd92d5a..a2b52d1 100644
--- a/src/elements/Display.lua
+++ b/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()
diff --git a/src/elements/Frame.lua b/src/elements/Frame.lua
index 43d53b1..0d29f77 100644
--- a/src/elements/Frame.lua
+++ b/src/elements/Frame.lua
@@ -117,7 +117,7 @@ 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
 
@@ -125,10 +125,7 @@ function Frame:mouse_drag(button, x, y)
         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
diff --git a/src/elements/Program.lua b/src/elements/Program.lua
index a92c4d0..903219d 100644
--- a/src/elements/Program.lua
+++ b/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
 
diff --git a/src/elements/SideNav.lua b/src/elements/SideNav.lua
index 94894fe..29000b2 100644
--- a/src/elements/SideNav.lua
+++ b/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
diff --git a/src/elements/TabControl.lua b/src/elements/TabControl.lua
index 9bfb4ef..9fbd4de 100644
--- a/src/elements/TabControl.lua
+++ b/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
diff --git a/src/elements/Tree.lua b/src/elements/Tree.lua
index ed89e84..fdf1843 100644
--- a/src/elements/Tree.lua
+++ b/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()