Refactor documentation for Container, Table, and Tree elements to improve clarity and usage examples

src/elements/Container.lua

@@ -6,13 +6,7 @@ local split = require("libraries/utils").split
 ---@configDescription The container class. It is a visual element that can contain other elements. It is the base class for all containers
 ---@configDefault true
 
---- A fundamental layout element that manages child UI components. Containers handle element organization, event propagation, 
+--- A fundamental layout element that manages child UI components. Containers handle element organization, event propagation, rendering hierarchy, and coordinate space management.
---- rendering hierarchy, and coordinate space management. They serve as the backbone of Basalt's UI structure by providing:
---- - Child element management and organization
---- - Event bubbling and distribution
---- - Visibility calculations and clipping
---- - Focus management
---- - Coordinate space transformation
 ---@class Container : VisualElement
 local Container = setmetatable({}, VisualElement)
 Container.__index = Container

src/elements/Table.lua

@@ -3,9 +3,33 @@ local tHex = require("libraries/colorHex")
 
 --- This is the table class. It provides a sortable data grid with customizable columns, row selection, and scrolling capabilities. Built on Collection for consistent item management.
 --- @usage [[
---- local people = container:addTable():setWidth(40)
+--- local peopleTable = main:addTable()
---- people:setColumns({{name="Name",width=12}, {name="Age",width=10}, {name="Country",width=15}})
+---     :setPosition(1, 2)
---- people:addRow("Alice", 30, "USA"):addRow("Bob", 25, "UK")
+---     :setSize(49, 10)
+---     :setColumns({
+---         {name = "Name", width = 15},
+---         {name = "Age", width = 8},
+---         {name = "Country", width = 12},
+---         {name = "Score", width = 10}
+---     })
+---     :setBackground(colors.black)
+---     :setForeground(colors.white)
+--- 
+--- peopleTable:addRow("Alice", 30, "USA", 95)
+--- peopleTable:addRow("Bob", 25, "UK", 87)
+--- peopleTable:addRow("Charlie", 35, "Germany", 92)
+--- peopleTable:addRow("Diana", 28, "France", 88)
+--- peopleTable:addRow("Eve", 32, "Spain", 90)
+--- peopleTable:addRow("Frank", 27, "Italy", 85)
+--- peopleTable:addRow("Grace", 29, "Canada", 93)
+--- peopleTable:addRow("Heidi", 31, "Australia", 89)
+--- peopleTable:addRow("Ivan", 26, "Russia", 91)
+--- peopleTable:addRow("Judy", 33, "Brazil", 86)
+--- peopleTable:addRow("Karl", 34, "Sweden", 84)
+--- peopleTable:addRow("Laura", 24, "Norway", 82)
+--- peopleTable:addRow("Mallory", 36, "Netherlands", 83)
+--- peopleTable:addRow("Niaj", 23, "Switzerland", 81)
+--- peopleTable:addRow("Olivia", 38, "Denmark", 80)
 --- ]]
 ---@class Table : Collection
 local Table = setmetatable({}, Collection)

src/elements/Tree.lua

@@ -16,8 +16,111 @@ local function flattenTree(nodes, expandedNodes, level, result)
     return result
 end
 
---- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed,
+--- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed, with support for selection and scrolling.
---- with support for selection and scrolling.
+---run [[
+--- local basaltg = require("basalt")
+--- local main = basalt.getMainFrame()
+--- 
+--- local fileTree = main:addTree()
+---     :setPosition(2, 2)
+---     :setSize(15, 15)
+---     :setBackground(colors.black)
+---     :setForeground(colors.white)
+---     :setSelectedBackgroundColor(colors.blue)
+---     :setSelectedForegroundColor(colors.white)
+---     :setScrollBarColor(colors.lightGray)
+---     :setScrollBarBackgroundColor(colors.gray)
+--- 
+--- -- Build a file system-like tree structure
+--- local treeData = {
+---     {
+---         text = "Root",
+---         children = {
+---             {
+---                 text = "Documents",
+---                 children = {
+---                     {text = "report.txt"},
+---                     {text = "notes.txt"},
+---                     {text = "todo.txt"}
+---                 }
+---             },
+---             {
+---                 text = "Pictures",
+---                 children = {
+---                     {text = "vacation.png"},
+---                     {text = "family.jpg"},
+---                     {
+---                         text = "Archive",
+---                         children = {
+---                             {text = "old_photo1.jpg"},
+---                             {text = "old_photo2.jpg"},
+---                             {text = "old_photo3.jpg"}
+---                         }
+---                     }
+---                 }
+---             },
+---             {
+---                 text = "Music",
+---                 children = {
+---                     {text = "song1.mp3"},
+---                     {text = "song2.mp3"},
+---                     {text = "song3.mp3"},
+---                     {text = "song4.mp3"}
+---                 }
+---             },
+---             {
+---                 text = "Videos",
+---                 children = {
+---                     {text = "movie1.mp4"},
+---                     {text = "movie2.mp4"}
+---                 }
+---             },
+---             {
+---                 text = "Projects",
+---                 children = {
+---                     {
+---                         text = "ProjectA",
+---                         children = {
+---                             {text = "src"},
+---                             {text = "tests"},
+---                             {text = "README.md"}
+---                         }
+---                     },
+---                     {
+---                         text = "ProjectB",
+---                         children = {
+---                             {text = "main.lua"},
+---                             {text = "config.lua"}
+---                         }
+---                     }
+---                 }
+---             }
+---         }
+---     }
+--- }
+--- 
+--- fileTree:setNodes(treeData)
+--- local textLabel = main:addLabel()
+---     :setPosition(2, 18)
+---     :setForeground(colors.yellow)
+---     :setText("Selected: None")
+--- 
+--- -- Handle node selection
+--- fileTree:onSelect(function(self, node)
+---     textLabel
+---         :setText("Selected: " .. node.text)
+---         :setPosition(2, 18)
+---         :setForeground(colors.yellow)
+--- end)
+---
+--- -- Info label
+--- main:addLabel()
+---     :setText("Click nodes to expand/collapse | Scroll to navigate")
+---     :setPosition(2, 1)
+---     :setForeground(colors.lightGray)
+--- 
+--- basalt.run()
+---]]
 ---@class Tree : VisualElement
 local Tree = setmetatable({}, VisualElement)
 Tree.__index = Tree