From f89c63938375cc90a6e01041aff7db9624f9de75 Mon Sep 17 00:00:00 2001
From: NoryiE <NoryiE@users.noreply.github.com>
Date: Thu, 30 Oct 2025 13:13:21 +0000
Subject: [PATCH] deploy: a967cde11541e369b661a33bd76f38a0bc3fd992

---
 docs/references/elements/Accordion.md   | 185 ++++++++++++++++++++++++
 docs/references/elements/Breadcrumb.md  |  53 +++++++
 docs/references/elements/ContextMenu.md | 148 +++++++++++++++++++
 docs/references/elements/Dialog.md      |  75 ++++++++++
 docs/references/elements/Toast.md       |  95 ++++++++++++
 5 files changed, 556 insertions(+)
 create mode 100644 docs/references/elements/Accordion.md
 create mode 100644 docs/references/elements/Breadcrumb.md
 create mode 100644 docs/references/elements/ContextMenu.md
 create mode 100644 docs/references/elements/Dialog.md
 create mode 100644 docs/references/elements/Toast.md

diff --git a/docs/references/elements/Accordion.md b/docs/references/elements/Accordion.md
new file mode 100644
index 0000000..85753f6
--- /dev/null
+++ b/docs/references/elements/Accordion.md
@@ -0,0 +1,185 @@
+# Accordion
+_The Accordion is a container that provides collapsible panel functionality_
+
+Extends: `Container`
+
+## Examples (Executable)
+```lua run
+local basalt = require("basalt")
+
+local main = basalt.getMainFrame()
+
+-- Create an Accordion
+local accordion = main:addAccordion({
+x = 2,
+y = 2,
+width = 30,
+height = 15,
+allowMultiple = true, -- Only one panel open at a time
+headerBackground = colors.gray,
+headerTextColor = colors.white,
+expandedHeaderBackground = colors.lightBlue,
+expandedHeaderTextColor = colors.white,
+})
+
+-- Panel 1: Info
+local infoPanel = accordion:newPanel("Information", true) -- starts expanded
+infoPanel:addLabel({
+x = 2,
+y = 1,
+text = "This is an accordion",
+foreground = colors.yellow
+})
+infoPanel:addLabel({
+x = 2,
+y = 2,
+text = "with collapsible panels.",
+foreground = colors.white
+})
+
+-- Panel 2: Settings
+local settingsPanel = accordion:newPanel("Settings", false)
+settingsPanel:addLabel({
+x = 2,
+y = 1,
+text = "Volume:",
+foreground = colors.white
+})
+local volumeSlider = settingsPanel:addSlider({
+x = 10,
+y = 1,
+width = 15,
+value = 50
+})
+settingsPanel:addLabel({
+x = 2,
+y = 3,
+text = "Auto-save:",
+foreground = colors.white
+})
+settingsPanel:addSwitch({
+x = 13,
+y = 3,
+})
+
+-- Panel 3: Actions
+local actionsPanel = accordion:newPanel("Actions", false)
+local statusLabel = actionsPanel:addLabel({
+x = 2,
+y = 4,
+text = "Ready",
+foreground = colors.lime
+})
+
+actionsPanel:addButton({
+x = 2,
+y = 1,
+width = 10,
+height = 1,
+text = "Save",
+background = colors.green,
+foreground = colors.white,
+})
+
+actionsPanel:addButton({
+x = 14,
+y = 1,
+width = 10,
+height = 1,
+text = "Cancel",
+background = colors.red,
+foreground = colors.white,
+})
+
+-- Panel 4: About
+local aboutPanel = accordion:newPanel("About", false)
+aboutPanel:addLabel({
+x = 2,
+y = 1,
+text = "Basalt Accordion v1.0",
+foreground = colors.white
+})
+aboutPanel:addLabel({
+x = 2,
+y = 2,
+text = "A collapsible panel",
+foreground = colors.gray
+})
+aboutPanel:addLabel({
+x = 2,
+y = 3,
+text = "component for UI.",
+foreground = colors.gray
+})
+
+-- Instructions
+main:addLabel({
+x = 2,
+y = 18,
+text = "Click panel headers to expand/collapse",
+foreground = colors.lightGray
+})
+
+basalt.run()
+```
+
+## Properties
+
+|Property|Type|Default|Description|
+|---|---|---|---|
+|panels|table|{}|List of panel definitions|
+|panelHeaderHeight|number|1|Height of each panel header|
+|allowMultiple|boolean|false|Allow multiple panels to be open at once|
+|headerBackground|color|gray|Background color for panel headers|
+|headerTextColor|color|white|Text color for panel headers|
+|expandedHeaderBackground|color|lightGray|Background color for expanded panel headers|
+|expandedHeaderTextColor|color|black|Text color for expanded panel headers|
+
+## Functions
+
+|Method|Returns|Description|
+|---|---|---|
+|[Accordion:newPanel](#accordion-newpanel-title-expanded)|table|Creates a new accordion panel|
+|[Accordion:togglePanel](#accordion-togglepanel-panelid)|Accordion|Toggles a panel's expanded state|
+|[Accordion:expandPanel](#accordion-expandpanel-panelid)|Accordion|Expands a specific panel|
+|[Accordion:collapsePanel](#accordion-collapsepanel-panelid)|Accordion|Collapses a specific panel|
+|[Accordion:getPanel](#accordion-getpanel-panelid)|container|Gets a panel container by ID|
+
+## Accordion:newPanel(title, expanded)
+
+Creates a new panel and returns the panel's container
+
+### Parameters
+* `title` `string` The title of the panel
+* `expanded` `boolean` Whether the panel starts expanded (default: false)
+
+### Returns
+* `table` `panelContainer` The container for this panel
+
+## Accordion:togglePanel(panelId)
+### Parameters
+* `panelId` `number` The ID of the panel to toggle
+
+### Returns
+* `Accordion` `self` For method chaining
+
+## Accordion:expandPanel(panelId)
+### Parameters
+* `panelId` `number` The ID of the panel to expand
+
+### Returns
+* `Accordion` `self` For method chaining
+
+## Accordion:collapsePanel(panelId)
+### Parameters
+* `panelId` `number` The ID of the panel to collapse
+
+### Returns
+* `Accordion` `self` For method chaining
+
+## Accordion:getPanel(panelId)
+### Parameters
+* `panelId` `number` The ID of the panel
+
+### Returns
+* `container` `The` panel's container or nil
diff --git a/docs/references/elements/Breadcrumb.md b/docs/references/elements/Breadcrumb.md
new file mode 100644
index 0000000..5e1b106
--- /dev/null
+++ b/docs/references/elements/Breadcrumb.md
@@ -0,0 +1,53 @@
+# Breadcrumb
+
+Extends: `VisualElement`
+
+## Properties
+
+|Property|Type|Default|Description|
+|---|---|---|---|
+|path|table|{}|Array of strings representing the breadcrumb segments|
+|clickable|true|boolean|Whether the segments are clickable|
+|autoSize|false|boolean|Whether to resize the element width automatically based on text|
+
+## Functions
+
+|Method|Returns|Description|
+|---|---|---|
+|[Breadcrumb.new](#breadcrumb-new)|table|Creates a new Breadcrumb instance|
+|[Breadcrumb:init](#breadcrumb-init-props-basalt)|-|Initializes the Breadcrumb instance|
+|[Breadcrumb:mouse_click](#breadcrumb-mouse-click-button-x-y)|boolean|Handles mouse click events|
+|[Breadcrumb:onSelect](#breadcrumb-onselect-callback)|Breadcrumb|Registers a callback for the select event|
+
+## Breadcrumb.new()
+### Returns
+* `table` self
+
+## Breadcrumb:init(props, basalt)
+### Parameters
+* `props` `table`
+* `basalt` `table`
+
+## Breadcrumb:mouse_click(button, x, y)
+### Parameters
+* `button` `number`
+* `x` `number`
+* `y` `number`
+
+### Returns
+* `boolean` handled
+
+## Breadcrumb:onSelect(callback)
+
+Registers a callback for the select event
+
+### Parameters
+* `callback` `function` The callback function to register
+
+### Returns
+* `Breadcrumb` `self` The Breadcrumb instance
+
+### Usage
+```lua
+breadcrumb:onSelect(function(segmentIndex, path) print("Navigated to segment:", segmentIndex, path) end)
+```
diff --git a/docs/references/elements/ContextMenu.md b/docs/references/elements/ContextMenu.md
new file mode 100644
index 0000000..d6735f1
--- /dev/null
+++ b/docs/references/elements/ContextMenu.md
@@ -0,0 +1,148 @@
+# ContextMenu
+_The ContextMenu displays a list of clickable items with optional submenus_
+
+Extends: `Container`
+
+## Examples (Executable)
+```lua run
+local basalt = require("basalt")
+
+local main = basalt.getMainFrame()
+
+-- Create a label that shows the selected action
+local statusLabel = main:addLabel({
+x = 2,
+y = 2,
+text = "Right-click anywhere!",
+foreground = colors.yellow
+})
+
+-- Create a ContextMenu
+local contextMenu = main:addContextMenu({
+x = 10,
+y = 5,
+background = colors.black,
+foreground = colors.white,
+})
+
+contextMenu:setItems({
+{
+label = "Copy",
+onClick = function()
+statusLabel:setText("Action: Copy")
+end
+},
+{
+label = "Paste",
+onClick = function()
+statusLabel:setText("Action: Paste")
+end
+},
+{
+label = "Delete",
+background = colors.red,
+foreground = colors.white,
+onClick = function()
+statusLabel:setText("Action: Delete")
+end
+},
+{label = "---", disabled = true},
+{
+label = "More Options",
+submenu = {
+{
+label = "Option 1",
+onClick = function()
+statusLabel:setText("Action: Option 1")
+end
+},
+{
+label = "Option 2",
+onClick = function()
+statusLabel:setText("Action: Option 2")
+end
+},
+{label = "---", disabled = true},
+{
+label = "Nested",
+submenu = {
+{
+label = "Deep 1",
+onClick = function()
+statusLabel:setText("Action: Deep 1")
+end
+}
+}
+}
+}
+},
+{label = "---", disabled = true},
+{
+label = "Exit",
+onClick = function()
+statusLabel:setText("Action: Exit")
+end
+}
+})
+
+-- Open menu on right-click anywhere
+main:onClick(function(self, button, x, y)
+if button == 2 then
+contextMenu.set("x", x)
+contextMenu.set("y", y)
+contextMenu:open()
+basalt.LOGGER.info("Context menu opened at (" .. x .. ", " .. y .. ")")
+end
+end)
+
+basalt.run()
+```
+
+## Properties
+
+|Property|Type|Default|Description|
+|---|---|---|---|
+|items|table|{}|List of menu items|
+|isOpen|boolean|false|Whether the menu is currently open|
+|openSubmenu|table|nil|Currently open submenu data|
+|itemHeight|number|1|Height of each menu item|
+
+## Functions
+
+|Method|Returns|Description|
+|---|---|---|
+|[ContextMenu:setItems](#contextmenu-setitems-items)|ContextMenu|Sets the menu items from a table|
+|[ContextMenu:open](#contextmenu-open)|ContextMenu|Opens the context menu|
+|[ContextMenu:close](#contextmenu-close)|ContextMenu|Closes the context menu|
+|[ContextMenu:closeAll](#contextmenu-closeall)|ContextMenu|Closes the root menu and all child menus|
+
+## ContextMenu:setItems(items)
+
+Sets the menu items
+
+### Parameters
+* `items` `table` Array of item definitions
+
+### Returns
+* `ContextMenu` `self` For method chaining
+
+## ContextMenu:open()
+
+Opens the menu
+
+### Returns
+* `ContextMenu` `self` For method chaining
+
+## ContextMenu:close()
+
+Closes the menu and any submenus
+
+### Returns
+* `ContextMenu` `self` For method chaining
+
+## ContextMenu:closeAll()
+
+Closes the entire menu chain (parent and all submenus)
+
+### Returns
+* `ContextMenu` `self` For method chaining
diff --git a/docs/references/elements/Dialog.md b/docs/references/elements/Dialog.md
new file mode 100644
index 0000000..757e633
--- /dev/null
+++ b/docs/references/elements/Dialog.md
@@ -0,0 +1,75 @@
+# Dialog
+_A dialog overlay system that provides common dialog types such as alert, confirm, and prompt._
+
+Extends: `Frame`
+
+## Properties
+
+|Property|Type|Default|Description|
+|---|---|---|---|
+|title|string|""|The dialog title|
+|primaryColor|color|lime|Primary button color (OK, confirm actions)|
+|secondaryColor|color|lightGray|Secondary button color (Cancel, dismiss actions)|
+|buttonForeground|color|black|Foreground color for buttons|
+|modal|boolean|true|If true, blocks all events outside the dialog|
+
+## Functions
+
+|Method|Returns|Description|
+|---|---|---|
+|[Dialog:show](#dialog-show)|Dialog|Shows the dialog|
+|[Dialog:close](#dialog-close)|Dialog|Closes the dialog|
+|[Dialog:alert](#dialog-alert-title-message-callback)|Dialog|Creates a simple alert dialog|
+|[Dialog:confirm](#dialog-confirm-title-message-callback)|Dialog|Creates a confirm dialog|
+|[Dialog:prompt](#dialog-prompt-title-message-default-callback)|Dialog|Creates a prompt dialog with input|
+
+## Dialog:show()
+
+Shows the dialog
+
+### Returns
+* `Dialog` `self` The Dialog instance
+
+## Dialog:close()
+
+Closes the dialog
+
+### Returns
+* `Dialog` `self` The Dialog instance
+
+## Dialog:alert(title, message, callback?)
+
+Creates a simple alert dialog
+
+### Parameters
+* `title` `string` The alert title
+* `message` `string` The alert message
+* `callback` *(optional)* `function` Callback when OK is clicked
+
+### Returns
+* `Dialog` `self` The Dialog instance
+
+## Dialog:confirm(title, message, callback)
+
+Creates a confirm dialog
+
+### Parameters
+* `title` `string` The dialog title
+* `message` `string` The confirmation message
+* `callback` `function` Callback (receives boolean result)
+
+### Returns
+* `Dialog` `self` The Dialog instance
+
+## Dialog:prompt(title, message, default?, callback?)
+
+Creates a prompt dialog with input
+
+### Parameters
+* `title` `string` The dialog title
+* `message` `string` The prompt message
+* `default` *(optional)* `string` Default input value
+* `callback` *(optional)* `function` Callback (receives input text or nil if cancelled)
+
+### Returns
+* `Dialog` `self` The Dialog instance
diff --git a/docs/references/elements/Toast.md b/docs/references/elements/Toast.md
new file mode 100644
index 0000000..f6c1c09
--- /dev/null
+++ b/docs/references/elements/Toast.md
@@ -0,0 +1,95 @@
+# Toast
+_A toast notification element that displays temporary messages with optional icons and auto-hide functionality._
+_The element is always visible but only renders content when a message is shown._
+
+Extends: `VisualElement`
+
+## Properties
+
+|Property|Type|Default|Description|
+|---|---|---|---|
+|title|string|""|The title text of the toast|
+|message|string|""|The message text of the toast|
+|duration|number|3|Duration in seconds before the toast auto-hides|
+|toastType|string|"default"|Type of toast: default, success, error, warning, info|
+|autoHide|boolean|true|Whether the toast should automatically hide after duration|
+|active|boolean|false|Whether the toast is currently showing a message|
+|colorMap|table|Map|of toast types to their colors|
+
+## Functions
+
+|Method|Returns|Description|
+|---|---|---|
+|[Toast:show](#toast-show-titleormessage-messageorduration-duration)|Toast|Shows a toast message|
+|[Toast:hide](#toast-hide)|Toast|Hides the toast|
+|[Toast:success](#toast-success-titleormessage-messageorduration-duration)|Toast|Shows a success toast|
+|[Toast:error](#toast-error-titleormessage-messageorduration-duration)|Toast|Shows an error toast|
+|[Toast:warning](#toast-warning-titleormessage-messageorduration-duration)|Toast|Shows a warning toast|
+|[Toast:info](#toast-info-titleormessage-messageorduration-duration)|Toast|Shows an info toast|
+
+## Toast:show(titleOrMessage, messageOrDuration?, duration?)
+
+Shows a toast message
+
+### Parameters
+* `titleOrMessage` `string` The title (if message provided) or the message (if no message)
+* `messageOrDuration` *(optional)* `string|number` The message (if string) or duration (if number)
+* `duration` *(optional)* `number` Duration in seconds
+
+### Returns
+* `Toast` `self` The Toast instance
+
+## Toast:hide()
+
+Hides the toast
+
+### Returns
+* `Toast` `self` The Toast instance
+
+## Toast:success(titleOrMessage, messageOrDuration?, duration?)
+
+Shows a success toast
+
+### Parameters
+* `titleOrMessage` `string` The title or message
+* `messageOrDuration` *(optional)* `string|number` The message or duration
+* `duration` *(optional)* `number` Duration in seconds
+
+### Returns
+* `Toast` `self` The Toast instance
+
+## Toast:error(titleOrMessage, messageOrDuration?, duration?)
+
+Shows an error toast
+
+### Parameters
+* `titleOrMessage` `string` The title or message
+* `messageOrDuration` *(optional)* `string|number` The message or duration
+* `duration` *(optional)* `number` Duration in seconds
+
+### Returns
+* `Toast` `self` The Toast instance
+
+## Toast:warning(titleOrMessage, messageOrDuration?, duration?)
+
+Shows a warning toast
+
+### Parameters
+* `titleOrMessage` `string` The title or message
+* `messageOrDuration` *(optional)* `string|number` The message or duration
+* `duration` *(optional)* `number` Duration in seconds
+
+### Returns
+* `Toast` `self` The Toast instance
+
+## Toast:info(titleOrMessage, messageOrDuration?, duration?)
+
+Shows an info toast
+
+### Parameters
+* `titleOrMessage` `string` The title or message
+* `messageOrDuration` *(optional)* `string|number` The message or duration
+* `duration` *(optional)* `number` Duration in seconds
+
+### Returns
+* `Toast` `self` The Toast instance