Guides for docs

2025-02-23 13:24:59 +01:00
parent 781690e462
commit 1f10b7eadf
13 changed files with 309 additions and 1254 deletions
--- a/docs/guides/animations.md
+++ b/docs/guides/animations.md
@@ -9,72 +9,91 @@ Animations in Basalt work with:
 - **Chains**: Multiple sequences that can be controlled together
 - **Timing**: Control over duration and easing of animations

-## Available Animations
+`element:animate()` creates a new Animation object. Each animation method accepts a duration parameter (in seconds).

-### Movement
+### Core Animation Methods
 ```lua
 element:animate()
-    :move(x, y, duration)    -- Moves to new position
+    :offset(x, y, duration)       -- Animate offset
+    :size(w, h, duration)         -- Animate size
+    :position(x, y, duration)     -- Animate position
+    :textColor(color, duration)   -- Animate text color
+    :background(color, duration)  -- Animate background color
 ```

-### Visual Effects
-```lua
-element:animate()
-    :size(width, height, duration)
-```
-
-### Text Animations
-```lua
-element:animate()
-    :typewrite(property, text, duration) -- Typing effect
-    :text(text, duration)               -- Instant text change
-```
-
-## Animation Control
-
-Control your animations using these methods:
+### Animation Control
 ```lua
 local anim = element:animate()
-    :move(10, 5, 1)
-    :start()
+    :offset(5, 0, 1)
+    :start()                     -- Start the animation

-anim:pause()    -- Pause animation
-anim:resume()   -- Resume animation
-anim:stop()     -- Stop animation
-anim:cancel()   -- Cancel animation
+anim:pause()                     -- Pause animation
+anim:resume()                    -- Resume animation
+anim:stop()                      -- Stop animation
 ```

-## Sequences
+## Understanding Sequences

-Chain multiple animations together:
+Sequences allow you to create complex animations by controlling when each animation plays. By default, all animations in a chain play simultaneously. Using `:sequence()` creates a new group that waits for the previous animations to complete.
+
+### Basic Example
 ```lua
+-- Without sequences (animations play at the same time):
 element:animate()
-    :move(10, 5, 1)        -- First sequence
-    :sequence()            -- Start new sequence
-    :move(20, 5, 1)       -- Plays after first sequence
+    :position(10, 5, 1)     -- These three animations
+    :size(5, 5, 1)         -- all start and play
+    :background(colors.red, 1)  -- simultaneously
+    :start()
+
+-- With sequences (animations play one after another):
+element:animate()
+    :position(10, 5, 1)     -- Plays first
    :sequence()
-    :background(colors.red, 0.5)
+    :size(5, 5, 1)         -- Starts after position completes
+    :sequence()
+    :background(colors.red, 1)  -- Starts after size completes
    :start()
 ```

-## Event Handling
+### Advanced Usage
+```lua
+-- Complex movement pattern
+element:animate()
+    :position(10, 5, 0.5)   -- Move right
+    :sequence()
+    :position(10, 10, 0.5)  -- Then down
+    :sequence()
+    :position(5, 10, 0.5)   -- Then left
+    :sequence()
+    :position(5, 5, 0.5)    -- Then up
+    :onDone(function()
+        -- Called when entire sequence completes
+    end)
+    :start()

-Animations support various events:
+-- Mixing simultaneous and sequential animations
+element:animate()
+    -- These two happen together
+    :position(10, 5, 1)
+    :background(colors.blue, 1)
+    :sequence()
+    -- These two also happen together, but after the first group
+    :position(5, 5, 1)
+    :background(colors.red, 1)
+    :start()
+```
+
+### Callbacks
 ```lua
 element:animate()
-    :move(10, 5, 1)
-    :onStart(function() 
-        -- Called when animation starts
-    end)
-    :onDone(function() 
-        -- Called when animation completes
-    end)
+    :offset(5, 0, 1)
+    :onStart(function() end)     -- When animation starts
+    :onDone(function() end)      -- When animation completes
+    :onStep(function() end)      -- Every animation step
    :start()
 ```

 ## Tips & Best Practices
-
 - Use sequences for complex animations
- Keep animations short and responsive
- Consider using events for coordinating multiple animations
- Test animations on different computer tiers
+- Keep duration times reasonable (0.1-2 seconds)
+- Consider using callbacks for state management
--- a/docs/guides/download.md
+++ b/docs/guides/download.md
@@ -1,6 +1,6 @@
 # Download

-Basalt is available in two versions: the dev version, ideal for develpoement and the release version which is meant for production
+Basalt is available in two versions: the dev version, ideal for develpoement and the release version which is meant for production. Basalt is also available on [PineStore](https://pinestore.cc/projects/15/basalt)

 ## Downloading Basalt

@@ -28,18 +28,4 @@ This is the default bundle version of Basalt, containing essential files for a U

 ```
 wget run https://raw.githubusercontent.com/Pyroxenium/basalt-docs/main/install.lua release
-```
-
-## Update Basalt
-
-The following command will update the project for you
-
-To execute the update command, use the following:
-
-```
-wget run https://raw.githubusercontent.com/Pyroxenium/basalt-docs/main/install.lua update
-```
-
-::: info
-This [config](https://github.com/Pyroxenium/Basalt2/config.json) file is used to check if a update needs to be done.
-:::
+```
--- a/docs/guides/faq.md
+++ b/docs/guides/faq.md
@@ -0,0 +1,83 @@
+# Frequently Asked Questions
+
+## General
+
+### What is Basalt?
+Basalt is a UI framework for CC:Tweaked that helps you create user interfaces easily and efficiently. It provides pre-built components, event handling, and advanced features like animations and themes.
+
+### Why should I use Basalt instead of direct terminal manipulation?
+Basalt handles many complex aspects automatically:
+- Event management
+- Screen rendering
+- Component positioning
+- State management
+- Layout organization
+
+## Installation
+
+### How do I install Basalt?
+```lua
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua
+```
+
+### Can I customize my installation?
+Yes! The installer allows you to:
+- Choose between Release/Dev versions
+- Select specific components
+- Include LuaLS definitions
+- Enable minification
+
+## Common Issues
+
+### Why isn't my UI updating?
+Remember to call `basalt.run()` at the end of your program. Without it, your UI won't start.
+
+### Why are my elements not visible?
+Check:
+1. Element positions are within parent bounds
+2. Parent container is large enough
+3. Element's `visible` property is true
+4. Z-index conflicts with other elements
+
+### How do I handle screen resizes?
+Use dynamic positioning with strings, or use functions:
+```lua
+element:setPosition("{parent.width - 5}", 5)  -- 5 from right edge
+element:setSize("{parent.width - 10}", 5)     -- 5 padding on each side
+element:setPosition(function(self)            -- Another example, but as function call
+    return self:getParent() - 5
+end, 5)
+```
+
+## Development
+
+### How do I add custom plugins?
+Create a new plugin in the plugins directory. See [pluginExample](https://github.com/Pyroxenium/Basalt2/blob/main/examples/pluginExample.lua) for a example on how to create plugins
+
+### Where can I find more examples?
+- Check the examples directory in the repository
+- Visit our [GitHub](https://github.com/Pyroxenium/Basalt2)
+- Join our [Discord](https://discord.gg/yNNnmBVBpE)
+
+### How do I contribute?
+1. Fork the repository
+2. Create a feature branch
+3. Submit a pull request
+4. Join our Discord for discussion
+
+## Performance
+
+### How can I optimize my Basalt application?
+Basalt does already a lot of optimization:
+- The render loop only runs when something visually changed (color, position, size,..) which means it only runs once, even if Basalt gets spammed with events (timer events or mouse events).
+- The event system is highly optimized:
+  - Events are only registered for elements that actually use them
+  - Events bubble up through the element hierarchy efficiently
+  - Event handlers are stored in a flat structure for quick access
+  - Events are automatically cleaned up when elements are removed
+  - Parent containers only receive events their children actually use
+
+Additional tips for optimization:
+- Group elements in Frames to reduce render calls
+- Use `setVisible(false)` instead of removing elements you'll need again
+- In case you need a LOT of elements you can use addDelayed{Element}, for example addDelayedButton instead of addButton
--- a/docs/guides/states.md
+++ b/docs/guides/states.md
@@ -0,0 +1,93 @@
+# State Management in Basalt
+
+States provide a powerful way to manage data and UI synchronization in your Basalt applications.
+
+## Core Concepts
+
+- **States**: Named values stored in frames
+- **Computed States**: States that depend on other states
+- **State Changes**: Automatic UI updates when states change
+- **State Listeners**: React to state changes
+
+## Basic State Methods
+
+```lua
+-- Initialize states
+frame:initializeState("name", defaultValue, triggerRender)
+frame:setState("name", newValue)
+frame:getState("name")
+
+-- Computed states
+frame:computed("name", function(self)
+    -- Calculate and return value based on other states
+end)
+
+-- Listen to changes
+frame:onStateChange("name", function(self, newValue)
+    -- React to state changes
+end)
+```
+
+## Complete Form Example
+
+Here's a comprehensive example showing state management in a form:
+
+```lua
+local main = basalt.getMainFrame()
+local form = main:addFrame()
+    :setSize("{parent.width - 4}", "{parent.height - 4}")
+    -- Initialize multiple states
+    :initializeState("username", "")
+    :initializeState("email", "")
+    :initializeState("age", 0)
+    :initializeState("submitted", false)
+    -- Add computed validation state
+    :computed("isValid", function(self)
+        local username = self:getState("username")
+        local email = self:getState("email")
+        local age = self:getState("age")
+        return #username > 0 and email:match(".+@.+") and age > 0
+    end)
+
+-- Input with state binding
+form:addInput()
+    :onChange(function(self, value)
+        form:setState("username", value)
+    end)
+
+-- Button reacting to computed state
+form:addButton()
+    :onStateChange("isValid", function(self, isValid)
+        self:setBackground(isValid and colors.lime or colors.gray)
+    end)
+```
+
+## Best Practices
+
+1. **State Initialization**
+   - Initialize all states at component creation
+   - Use meaningful default values
+   - Consider whether state changes should trigger renders
+
+2. **Computed States**
+   - Use for values that depend on multiple states
+   - Keep computations simple and efficient
+   - Avoid circular dependencies
+
+3. **State Updates**
+   - Update states through setState, not directly
+   - Use onStateChange for side effects
+   - Consider batching multiple state updates
+
+4. **Form Validation**
+   - Use computed states for form validation
+   - Update UI elements based on validation state
+   - Trigger actions only when validation passes
+
+## Tips
+
+- Use states for data that affects multiple components
+- Consider using tables for complex state
+- Keep state updates minimal and efficient
+- Use meaningful state names
+- Document state dependencies