### Fetch Elixir project dependencies
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Fetches and installs the defined dependencies for your Elixir project, including Raxol.
```bash
mix deps.get
```
--------------------------------
### Setup Raxol Project Dependencies and Database
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/components/visualization/testing-guide.md
Commands to fetch Elixir dependencies, compile the project, install Node.js dependencies for the VS Code extension, and set up the PostgreSQL test database for Raxol.
```bash
mix deps.get
mix compile
cd extensions/vscode
npm install
mix ecto.create
mix ecto.migrate
```
--------------------------------
### Start Raxol application in IEx
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Starts a Raxol application directly within an IEx session for quick testing and development.
```elixir
iex> Raxol.Core.Runtime.Lifecycle.start_application(MyRaxolApp.Application)
```
--------------------------------
### Configure Raxol application in mix.exs
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Configures the main application module in `mix.exs` to ensure the Raxol application starts correctly when the project is launched.
```elixir
def application do
[
extra_applications: [:logger],
mod: {MyRaxolApp.Application, []}
]
end
```
--------------------------------
### Start All Raxol Metrics System Components
Source: https://github.com/hydepwns/raxol/blob/master/lib/raxol/core/metrics/README.md
Provides a basic setup example demonstrating how to concurrently start all core components of the Raxol Metrics System: Unified Collector, Aggregator, Visualizer, and Alert Manager.
```Elixir
# Start all components
{:ok, collector} = Raxol.Core.Metrics.UnifiedCollector.start_link()
{:ok, aggregator} = Raxol.Core.Metrics.Aggregator.start_link()
{:ok, visualizer} = Raxol.Core.Metrics.Visualizer.start_link()
{:ok, alert_manager} = Raxol.Core.Metrics.AlertManager.start_link()
```
--------------------------------
### Create a new Elixir Mix project
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Initializes a new Elixir project and navigates into its directory. This is an optional step if you already have a project.
```bash
mix new my_raxol_app
cd my_raxol_app
```
--------------------------------
### Run Raxol Component Showcase Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Executes a specific Elixir example script that showcases Raxol components, useful for development and testing individual features.
```bash
mix run examples/snippets/showcase/component_showcase.exs
```
--------------------------------
### Raxol Application Keyboard Shortcut Implementation (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/keyboard_shortcuts_guide.md
Provides a complete Elixir application example demonstrating the setup of UX refinement, registration of multiple shortcuts (save, quit), and handling of key events within an `handle_event` callback.
```Elixir
defmodule MyApp do
use Raxol.App
alias Raxol.Core.KeyboardShortcuts
def start_link(_opts) do
# Setup
UXRefinement.init()
UXRefinement.enable_feature(:keyboard_shortcuts)
# Register shortcuts
KeyboardShortcuts.register_shortcut(:save, "Ctrl+S", &save/0,
context: :editor,
priority: :high
)
KeyboardShortcuts.register_shortcut(:quit, "Ctrl+Q", &quit/0)
# Start app
Raxol.Core.Runtime.Lifecycle.start_application(MyApp)
end
@impl true
def handle_event({:key, key_event}, _from, state) do
case KeyboardShortcuts.handle_key_event(key_event, state) do
{:ok, :handled, new_state} -> {:noreply, new_state}
{:ok, :not_handled, state} -> handle_other_key_input(key_event, state)
{:error, _reason, state} -> {:noreply, state}
end
end
end
```
--------------------------------
### Integrate Raxol application into supervision tree
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Defines an Elixir application module to start the Raxol application as part of a supervision tree, ensuring its lifecycle is managed by the OTP supervisor.
```elixir
defmodule MyRaxolApp.Application do
use Application
def start(_type, _args) do
children = [
{Raxol.Core.Runtime.Application, app: MyRaxolApp.Application}
]
opts = [strategy: :one_for_one, name: MyRaxolApp.Supervisor]
Supervisor.start_link(children, opts)
end
end
```
--------------------------------
### Install Elixir Dependencies
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Fetches and installs all necessary Elixir dependencies for the Raxol project using Mix, ensuring all required libraries are available.
```bash
mix deps.get
```
--------------------------------
### Install Raxol on Debian/Ubuntu via APT
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
After successfully setting up the Raxol APT repository, these commands update your local package lists and then install the `raxol` package using `apt`. This completes the installation process on Debian-based systems.
```bash
sudo apt update
sudo apt install raxol
```
--------------------------------
### Define Raxol application with Raxol.View functions
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Defines a Raxol application module using `Raxol.View` and component functions for UI definition. It includes `init/1` for initial state, `update/2` for state changes, and `render/1` for UI rendering.
```elixir
defmodule MyRaxolApp.Application do
use Raxol.Core.Runtime.Application
use Raxol.View
import Raxol.View.Elements
@impl true
def init(_context), do: %{count: 0}
@impl true
def update(:increment, state), do: %{state | count: state.count + 1}
def update(_, state), do: state
@impl true
def render(assigns) do
view do
box border: :single, padding: 1 do
text content: "Count: #{assigns.count}", color: :cyan, attributes: [:bold]
button label: "Increment", on_click: :increment
end
end
end
end
```
--------------------------------
### Install Raxol on macOS using Homebrew
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command uses Homebrew, the popular package manager for macOS, to install Raxol from the official tap. It provides a simple and recommended method for macOS users to get Raxol set up.
```bash
brew install hydepwns/raxol/raxol
```
--------------------------------
### Comprehensive Mouse Handler Example in Elixir
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/terminal/MouseHandling.md
A complete Elixir example demonstrating the initialization, configuration, event handling (click, motion, wheel), and selection management (start, update, get) of the Raxol.Terminal.Mouse component within a module.
```elixir
defmodule MyTerminal do
alias Raxol.Terminal.Mouse
def example do
# Create a new mouse handler
mouse = Mouse.new()
# Configure mouse handling
mouse = mouse
|> Mouse.enable_tracking()
|> Mouse.set_mode(:normal)
# Handle mouse events
{:ok, action} = Mouse.handle_event(mouse, {:click, 10, 20, :left})
mouse = Mouse.handle_motion(mouse, 15, 25)
# Work with selections
mouse = mouse
|> Mouse.start_selection(10, 10)
|> Mouse.update_selection(20, 10)
# Get selected text
{:ok, selected_text} = Mouse.get_selection(mouse)
# Handle scroll events
mouse = Mouse.handle_wheel(mouse, 1, :vertical)
end
end
```
--------------------------------
### Fetch Elixir Mix Dependencies
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
After adding Raxol to your `mix.exs` file, run this command in your terminal to download and install the declared dependencies. This step is crucial for making Raxol available in your Elixir project.
```bash
mix deps.get
```
--------------------------------
### Elixir Test Setup Helpers
Source: https://github.com/hydepwns/raxol/blob/master/docs/testing/tools.md
Defines Elixir functions to configure the test environment, including setting application environment variables, and placeholders for database and plugin setup.
```elixir
defmodule Raxol.Test.Utils.SetupHelpers do
def setup_test_environment do
Application.put_env(:raxol, :test_mode, true)
setup_test_database()
setup_test_plugins()
end
def setup_test_database do
# Setup test database
end
def setup_test_plugins do
# Setup test plugins
end
end
```
--------------------------------
### Elixir Test Setup and Cleanup Helpers
Source: https://github.com/hydepwns/raxol/blob/master/docs/testing/test_writing_guide.md
This snippet defines a module `Raxol.Test.SetupHelpers` for encapsulating common test environment setup and cleanup logic in Elixir. These functions can be reused across multiple test modules to ensure consistent and isolated test environments.
```Elixir
defmodule Raxol.Test.SetupHelpers do
def setup_test_environment do
# Setup test environment
end
def cleanup_test_environment do
# Cleanup test environment
end
end
```
--------------------------------
### Install Raxol on Windows using Winget
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command utilizes the Windows Package Manager (winget) to install Raxol on Windows systems. It offers a simple and efficient command-line method for installing applications on Windows.
```bash
winget install raxol
```
--------------------------------
### Raxol.Core.Config.Manager API Reference
Source: https://github.com/hydepwns/raxol/blob/master/docs/CONFIGURATION.md
API documentation for the Raxol.Core.Config.Manager module, detailing functions for configuration management including starting the manager, getting, setting, updating, deleting, and reloading configuration values.
```APIDOC
Raxol.Core.Config.Manager:
start_link/1: Start manager
get/2: Get value
set/3: Set value
update/3: Update value
delete/2: Delete value
get_all/0: Get all values
reload/0: Reload config
```
--------------------------------
### Run Raxol Examples
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/README.md
Commands to run basic and showcase examples of Raxol applications from the command line using `mix run`. The output is piped to `cat` for display.
```bash
mix run examples/basic/counter.exs | cat
mix run examples/showcase/component_showcase.exs | cat
```
--------------------------------
### Elixir Test State Management with Setup Blocks
Source: https://github.com/hydepwns/raxol/blob/master/docs/testing/test_writing_guide.md
This snippet demonstrates how to manage state within Elixir tests using `setup` blocks. It shows how to initialize state before a test runs and then use that state within the test to verify state updates, ensuring test isolation and reproducibility.
```Elixir
setup do
state = initial_state()
{:ok, %{state: state}}
end
test "updates state correctly", %{state: state} do
new_state = update_state(state)
assert state_changed_correctly?(state, new_state)
end
```
--------------------------------
### Run Elixir Documentation Browser Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/advanced/README.md
Demonstrates a browser for exploring Elixir module documentation, showcasing scrolling, asynchronous updates, and managing multiple views.
```elixir
mix run examples/advanced/documentation_browser.exs | cat
```
--------------------------------
### Elixir Function Documentation with @doc
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/style_guide.md
Shows how to document individual functions in Elixir using `@doc`. This example details the purpose of an event handler, its parameters, return values, and includes a practical usage example to guide developers.
```elixir
@doc """
Handles component events.
## Parameters
* `event` - The event to handle
* `state` - Current component state
## Returns
* `{new_state, commands}` - Updated state and commands
## Examples
handle_event(%{type: :click}, state)
"""
```
--------------------------------
### Define Raxol application with HEEx Sigil
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Defines a Raxol application module using the `~H` HEEx sigil for UI definition. It includes `init/1` for initial state, `update/2` for state changes, and `render/1` for UI rendering.
```elixir
defmodule MyRaxolApp.Application do
use Raxol.Core.Runtime.Application
@impl true
def init(_context), do: %{count: 0}
@impl true
def update(:increment, state), do: %{state | count: state.count + 1}
def update(_, state), do: state
@impl true
def render(assigns) do
~H"""
Count: <%= @count %>
"""
end
end
```
--------------------------------
### Install Missing Dependencies on Linux
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command installs common development libraries, `libssl-dev` and `libncurses5-dev`, which might be required for Raxol to compile or run correctly on Linux systems. It addresses potential 'Missing Dependencies' issues.
```bash
sudo apt install libssl-dev libncurses5-dev
```
--------------------------------
### Run Hello World Elixir Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/without-runtime/README.md
A minimal example showing how to create a terminal application without using the runtime.
```elixir
mix run examples/without-runtime/hello_world.exs | cat
```
--------------------------------
### Elixir Basic File Watching Setup and Lifecycle
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/file_watcher.md
This example demonstrates the fundamental steps to initialize, set up, update, and clean up file watching functionality. It shows how to manage the state for plugin directories and paths, and integrate with `FileWatcher.setup_file_watching`, `update_file_watcher`, and `cleanup_file_watching` functions.
```elixir
# Initialize file watching
state = %{
plugin_dirs: ["plugins"],
plugin_paths: %{"my_plugin" => "plugins/my_plugin.ex"},
file_watching_enabled?: false
}
# Setup file watching
{pid, enabled?} = FileWatcher.setup_file_watching(state)
state = %{state | file_watcher_pid: pid, file_watching_enabled?: enabled?}
# Update file watcher with new paths
state = FileWatcher.update_file_watcher(state)
# Cleanup on shutdown
state = FileWatcher.cleanup_file_watching(state)
```
--------------------------------
### Elixir Module Documentation with @moduledoc
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/style_guide.md
Provides an example of comprehensive module-level documentation in Elixir using `@moduledoc`. It outlines best practices for describing the component's purpose, features, props, and includes usage examples for clarity and maintainability.
```elixir
@moduledoc """
A clear, concise description of the component.
## Features
* Feature 1
* Feature 2
## Props
* `:prop1` - Description
* `:prop2` - Description
## Examples
MyComponent.new(id: "my-component")
"""
```
--------------------------------
### Elixir Component Testing with ExUnit
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/style_guide.md
Demonstrates how to structure component tests using ExUnit in Elixir. It covers testing component lifecycle events like initialization and mounting, as well as event handling for both valid and invalid inputs. The tests utilize `Raxol.ComponentTestHelpers` for setup and simulation.
```elixir
defmodule Raxol.UI.Components.Input.TextInputTest do
use ExUnit.Case, async: true
import Raxol.ComponentTestHelpers
describe "Component Lifecycle" do
test "initializes with props" do
component = create_test_component(TextInput, %{id: "test", value: "initial"})
assert component.state.value == "initial"
end
test "mounts correctly" do
component = create_test_component(TextInput, %{id: "test"})
{mounted, _} = simulate_lifecycle(component, &(&1))
assert mounted.state.mounted
end
end
describe "Event Handling" do
test "handles valid events" do
component = create_test_component(TextInput, %{id: "test"})
{updated, _} = simulate_event(component, %{type: :change, value: "new"})
assert updated.state.value == "new"
end
test "handles invalid events" do
component = create_test_component(TextInput, %{id: "test"})
{updated, _} = simulate_event(component, %{type: :invalid})
assert updated.state == component.state
end
end
end
```
--------------------------------
### Run Elixir Command System Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/advanced/README.md
Shows how to use the command system to execute asynchronous tasks and update the UI.
```elixir
mix run examples/advanced/commands.exs | cat
```
--------------------------------
### Add Raxol dependency to mix.exs
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/quick_start.md
Adds the Raxol library as a dependency to your Elixir project's `mix.exs` file, specifying a compatible version.
```elixir
def deps do
[
{:raxol, "~> 0.5.0"}
]
end
```
--------------------------------
### Launch Raxol Visualization in Native Terminal Mode
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/components/visualization/testing-guide.md
Command to directly launch the Raxol visualization components in the native terminal environment after the test setup script has been executed.
```bash
./scripts/run_native_terminal.sh
```
--------------------------------
### Manage Raxol Plugins in Elixir
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/api/README.md
Shows how to register, start, and stop plugins in the Raxol runtime. It also includes functions for listing, retrieving, and checking the enabled status of installed plugins.
```elixir
# Plugin registration and lifecycle
Raxol.Core.Runtime.Plugins.register(plugin)
Raxol.Core.Runtime.Plugins.start(plugin)
Raxol.Core.Runtime.Plugins.stop(plugin)
# Plugin management
Raxol.Core.Runtime.Plugins.list()
Raxol.Core.Runtime.Plugins.get(plugin_id)
Raxol.Core.Runtime.Plugins.enabled?(plugin_id)
```
--------------------------------
### Counter Example with Raxol
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/basic/README.md
A simple counter application demonstrating basic state management with increment and decrement functions using Raxol.
```Elixir
mix run examples/basic/counter.exs | cat
```
--------------------------------
### Run Event Viewer Elixir Example for Terminal Events
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/without-runtime/README.md
Shows how to capture and display terminal events like keyboard, mouse, and resize events.
```elixir
mix run examples/without-runtime/event_viewer.exs | cat
```
--------------------------------
### Add Raxol APT Repository on Debian/Ubuntu
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
These commands add the official Raxol APT repository to your Debian or Ubuntu system. It involves securely downloading the GPG key and then configuring your package manager to recognize the Raxol repository source.
```bash
curl -fsSL https://deb.raxol.dev/gpg | sudo gpg --dearmor -o /usr/share/keyrings/raxol-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/raxol-archive-keyring.gpg] https://deb.raxol.dev stable main" | sudo tee /etc/apt/sources.list.d/raxol.list
```
--------------------------------
### Run Elixir Text Editor Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/advanced/README.md
Illustrates a simple text editor, handling keyboard input, cursor positioning, and text manipulation.
```elixir
mix run examples/advanced/editor.exs | cat
```
--------------------------------
### Define a Complete Raxol UI Theme in Elixir
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/theming.md
Provides a comprehensive example of defining a full Raxol UI theme, including semantic colors, component-specific styles, theme variants (like high contrast), and UI role mappings. This Elixir code demonstrates how to instantiate a `Raxol.UI.Theming.Theme` struct with all necessary configurations for a dark theme.
```Elixir
theme = Raxol.UI.Theming.Theme.new(%{
id: :dark,
name: "Dark Theme",
description: "A dark theme for Raxol applications",
colors: %{
primary: Raxol.Style.Colors.Color.from_hex("#0077CC"),
secondary: Raxol.Style.Colors.Color.from_hex("#666666"),
background: Raxol.Style.Colors.Color.from_hex("#1E1E1E"),
surface: Raxol.Style.Colors.Color.from_hex("#2D2D2D"),
text: Raxol.Style.Colors.Color.from_hex("#FFFFFF"),
error: Raxol.Style.Colors.Color.from_hex("#FF5555"),
warning: Raxol.Style.Colors.Color.from_hex("#FFB86C"),
success: Raxol.Style.Colors.Color.from_hex("#50FA7B")
},
component_styles: %{
panel: %{
border: :single,
padding: 1,
background: :surface,
foreground: :text
},
button: %{
padding: {0, 1},
text_style: [:bold],
background: :primary,
foreground: :white
},
text_field: %{
border: :single,
padding: {0, 1},
background: :surface,
foreground: :text
}
},
variants: %{
high_contrast: %{
colors: %{
primary: Raxol.Style.Colors.Color.from_hex("#0000FF"),
background: Raxol.Style.Colors.Color.from_hex("#000000"),
text: Raxol.Style.Colors.Color.from_hex("#FFFFFF")
}
}
},
ui_mappings: %{
app_background: :background,
surface_background: :surface,
primary_button: :primary,
secondary_button: :secondary,
text: :text,
error_text: :error,
warning_text: :warning,
success_text: :success
},
metadata: %{
author: "Raxol Team",
version: "1.0.0"
}
})
```
--------------------------------
### Resolve Erlang/OTP Build Failures on macOS with asdf
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Provides steps to troubleshoot Erlang/OTP build failures on macOS when using `asdf`, particularly issues related to missing C++ headers. Solutions include cleaning up failed installations, explicitly setting C/C++ compilers with Homebrew's LLVM, and verifying Xcode Command Line Tools.
```Bash
rm -rf ~/.asdf/installs/erlang/
asdf uninstall erlang
```
```Bash
brew install llvm
brew upgrade llvm
```
```Bash
export CC=/opt/homebrew/opt/llvm/bin/clang \
CXX=/opt/homebrew/opt/llvm/bin/clang++ \
LDFLAGS="-L/opt/homebrew/opt/llvm/lib" \
CPPFLAGS="-I/opt/homebrew/opt/llvm/include"
asdf install erlang 27.0.1
asdf reshim erlang
```
```Bash
xcode-select --install
```
--------------------------------
### Comprehensive Raxol Terminal Window Management Example (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/terminal/WindowManagement.md
A complete Elixir example demonstrating the creation, configuration, manipulation, and state persistence of Raxol terminal windows, including splitting and focusing.
```elixir
defmodule MyTerminal do
alias Raxol.Terminal.Windows
def example do
# Create a new window manager
windows = Windows.new()
# Create main window
{:ok, main_id} = Windows.create(windows, %{
title: "Main Terminal",
size: {80, 24}
})
# Split main window horizontally
{:ok, top_id} = Windows.split(windows, main_id, :horizontal)
# Configure windows
windows = windows
|> Windows.resize(main_id, {80, 40})
|> Windows.set_title(top_id, "Top Window")
|> Windows.focus(top_id)
# Save window state
{:ok, state} = Windows.save_state(windows)
# Later, restore state
{:ok, windows} = Windows.load_state(Windows.new(), state)
end
end
```
--------------------------------
### Comprehensive Raxol.Terminal.Input usage example
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/terminal/InputHandling.md
A complete example demonstrating the creation, configuration, and processing of keyboard and mouse input using the Raxol.Terminal.Input module within a `MyTerminal` module.
```Elixir
defmodule MyTerminal do
alias Raxol.Terminal.Input
def example do
# Create a new input handler
input = Input.new()
# Configure input handling
input = input
|> Input.set_input_mode(:normal)
|> Input.set_mouse_enabled(true)
|> Input.set_buffer_size(1000)
# Process some input
{:ok, input, actions} = input
|> Input.process_key("H")
|> Input.process_key("e")
|> Input.process_key("l")
|> Input.process_key("l")
|> Input.process_key("o")
# Handle mouse click
{:ok, input, actions} = Input.process_mouse(input, {:click, 10, 5})
# Get input history
history = Input.get_history(input)
end
end
```
--------------------------------
### Run Clock Elixir Example with Timer
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/without-runtime/README.md
Demonstrates how to create an application loop with a timer to update the UI periodically.
```elixir
mix run examples/without-runtime/clock.exs | cat
```
--------------------------------
### Run Elixir Snake Game Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/advanced/README.md
Presents a complete Snake game implementation, highlighting game loop, canvas drawing, and keypress handling.
```elixir
mix run examples/advanced/snake.exs | cat
```
--------------------------------
### Clone Raxol Repository
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Clones the Raxol project repository from GitHub and navigates into the project directory, preparing for local development.
```bash
git clone https://github.com/Hydepwns/raxol.git
cd raxol
```
--------------------------------
### Manage Shortcut Contexts in Raxol Elixir
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/accessibility/accessibility_guide.md
This example illustrates how to manage different UI contexts for keyboard shortcuts. It shows functions to set the current context, retrieve available shortcuts for that context, and display a help overview of all shortcuts, enabling dynamic shortcut behavior based on the application's state.
```Elixir
# Set current context
Raxol.Core.UXRefinement.set_shortcuts_context(:editor)
# Get available shortcuts for current context
shortcuts = Raxol.Core.UXRefinement.get_available_shortcuts()
# Show shortcuts help
Raxol.Core.UXRefinement.show_shortcuts_help()
```
--------------------------------
### Elixir: Registering a Custom Theme with Raxol's Color System
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/theming.md
Illustrates how to register a newly defined custom theme with the Raxol color system. This makes the theme available for application throughout the Raxol UI. The example shows a simplified registration using a map of colors.
```elixir
Raxol.Core.ColorSystem.register_theme(%{
primary: "#0077CC",
secondary: "#00AAFF",
background: "#001133",
foreground: "#FFFFFF",
accent: "#FF9900"
})
```
--------------------------------
### Create a Basic Raxol Application
Source: https://github.com/hydepwns/raxol/blob/master/README.md
Examples demonstrating how to create a simple 'Hello from Raxol!' application using both the declarative H-syntax and the programmatic View-syntax for UI rendering.
```Elixir
defmodule MyApp.Application do
use Raxol.Core.Runtime.Application
@impl true
def render(assigns) do
~H"""
Hello from Raxol!
"""
end
end
```
```Elixir
defmodule MyApp.Application do
use Raxol.Core.Runtime.Application
use Raxol.View
import Raxol.View.Elements
@impl true
def render(assigns) do
view do
box border: :single, padding: 1 do
text content: "Hello from Raxol!", color: :cyan, attributes: [:bold]
Progress.bar(0.75, width: 20)
end
end
end
end
```
--------------------------------
### Elixir: Defining a New Custom Theme in Raxol
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/theming.md
Provides a comprehensive example of how to define a new custom theme in Raxol. It demonstrates setting various theme attributes like ID, name, colors, component styles, variants (e.g., high contrast), UI mappings, and metadata. This is the primary way to extend Raxol's theming capabilities.
```elixir
defmodule MyApp.Themes.CustomTheme do
def theme do
Raxol.UI.Theming.Theme.new(%{
id: :custom,
name: "Custom Theme",
description: "A custom theme for my application",
colors: %{
primary: Raxol.Style.Colors.Color.from_hex("#0077CC"),
secondary: Raxol.Style.Colors.Color.from_hex("#666666"),
background: Raxol.Style.Colors.Color.from_hex("#FFFFFF"),
text: Raxol.Style.Colors.Color.from_hex("#333333")
},
component_styles: %{
panel: %{
border: :single,
padding: 1
},
button: %{
padding: {0, 1},
text_style: [:bold]
}
},
variants: %{
high_contrast: %{
colors: %{
primary: Raxol.Style.Colors.Color.from_hex("#0000FF"),
background: Raxol.Style.Colors.Color.from_hex("#000000"),
text: Raxol.Style.Colors.Color.from_hex("#FFFFFF")
}
}
},
ui_mappings: %{
app_background: :background,
surface_background: :surface,
primary_button: :primary,
secondary_button: :secondary,
text: :text
},
metadata: %{
author: "My Name",
version: "1.0.0"
}
})
end
end
```
--------------------------------
### Install Raxol on Arch Linux using Yay
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command uses `yay`, a popular AUR helper, to install Raxol on Arch Linux. It fetches and builds the package from the Arch User Repository, providing a convenient installation method for Arch users.
```bash
yay -S raxol
```
--------------------------------
### Architecture Demo
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/showcase/README.md
A simpler showcase demonstrating the core concepts: Components, Layout, and Theming.
```elixir
mix run examples/showcase/architecture_demo.exs | cat
```
--------------------------------
### Subscribe and Handle Raxol Plugin Manager Ready Event (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/roadmap/architecture/EventSystemExamples.md
This example illustrates subscribing to the ":plugin_manager_ready" event, which signals that the plugin manager has initialized. The handle_info/2 callback updates the component state, indicating the system is prepared to load plugins.
```Elixir
# Subscribe to plugin manager ready event
Raxol.Core.Runtime.Events.Dispatcher.subscribe(self(), [:plugin_manager_ready])
# Handle the event
def handle_info({:plugin_manager_ready, plugin_manager_pid}, state) do
# Plugin manager is ready to load plugins
{:noreply, %{state | plugin_manager_ready: true}}
end
```
--------------------------------
### Install Missing Dependencies on macOS
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command installs common development libraries, `openssl` and `ncurses`, using Homebrew, which might be required for Raxol to compile or run correctly on macOS systems. It helps resolve dependency-related errors.
```bash
brew install openssl ncurses
```
--------------------------------
### Run SelectList Component Showcase (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_component_reference/inputs/select_list.md
Demonstrates how to run the complete `SelectList` component showcase example in Elixir, providing a full demonstration of all its features.
```Elixir
alias Raxol.Examples.SelectListShowcase
Raxol.run(SelectListShowcase)
```
--------------------------------
### Component Showcase
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/showcase/README.md
Demonstrates a wide variety of available Raxol components, layouts, and basic theming.
```elixir
mix run examples/showcase/component_showcase.exs | cat
```
--------------------------------
### Multiple Views Navigation in Raxol
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/basic/README.md
Demonstrates how to handle multiple views and navigate between them within a Raxol application.
```Elixir
mix run examples/basic/multiple_views.exs | cat
```
--------------------------------
### Cloud Integration
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/showcase/README.md
Demonstrates how to integrate Raxol with cloud services, showing API calls, data visualization, and asynchronous operations. (Note: This is a script, not a TUI app).
```elixir
mix run examples/showcase/cloud_integration.exs | cat
```
--------------------------------
### APIDOC: Raxol Plugin Dependency Cycle Detection Example
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/04_extending_raxol/plugin_development.md
This conceptual example illustrates a dependency graph used by Raxol's dependency resolution system to detect circular dependencies. It shows how Tarjan's algorithm identifies true cycles, such as [A, B, C, D, E], which are flagged as errors during plugin initialization.
```APIDOC
A → B → C
↑ ↓ ↓
└── D ← E
Edges: A→B, B→C, C→E, E→D, D→A, B→D
Tarjan's algorithm will find the cycle: [A, B, C, D, E]
```
--------------------------------
### Check C Compiler Version
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Verifies the installation and version of the GCC C compiler, which is often required for compiling native interface functions (NIFs) in Elixir.
```bash
gcc --version
```
--------------------------------
### Elixir: Concurrent Load Test Example
Source: https://github.com/hydepwns/raxol/blob/master/docs/testing/performance_testing.md
Illustrates how to test concurrent operations under load using `assert_concurrent_performance`. It takes a list of operations and asserts their collective performance against a defined threshold.
```elixir
test "handles concurrent load" do
operations = [
fn -> # Operation 1
end,
fn -> # Operation 2
end
]
assert_concurrent_performance(operations, "concurrent operations", 5.0)
end
```
--------------------------------
### Bash: Raxol Database Setup and Migration Commands
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/components/database/README.md
These bash commands facilitate the initial setup, migration, and rollback of the Raxol database. They utilize custom scripts for creating and resetting the database, and `mix ecto` commands for managing migrations, ensuring the database schema is up-to-date.
```bash
# Create database and run migrations
./scripts/setup_db.sh
# Reset database (drop and recreate)
./scripts/setup_db.sh --reset
# Run migrations only
mix ecto.migrate
# Rollback migrations
mix ecto.rollback
```
--------------------------------
### Raxol Component Naming Conventions
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/style_guide.md
This APIDOC entry details the naming conventions for modules, functions, variables, and types within Raxol components, providing rules and examples for each category.
```APIDOC
Naming Conventions:
Module Names:
- Rule: Use PascalCase
- Rule: Group related components in namespaces
- Example: Raxol.UI.Components.Input.TextInput
Function Names:
- Rule: Use snake_case
- Rule: Use descriptive, action-oriented names
- Example: handle_text_change, validate_input
Variable Names:
- Rule: Use snake_case
- Rule: Use descriptive names that indicate purpose
- Example: current_value, is_valid
Type Names:
- Rule: Use snake_case
- Rule: Prefix with component name for clarity
- Example: text_input_props, text_input_state
```
--------------------------------
### Compile Elixir Project
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/DevelopmentSetup.md
Compiles the Raxol Elixir project, preparing all source code into executable bytecode for running the application.
```bash
mix compile
```
--------------------------------
### Initialize and Control Performance Monitoring
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/performance/PerformanceMonitoring.md
Demonstrates how to get an instance of the `ViewPerformance` class, start monitoring application performance, and stop monitoring when finished. This is the foundational step for using the Raxol performance system.
```typescript
import { ViewPerformance } from 'raxol/core/performance';
// Get an instance of the ViewPerformance class
const viewPerformance = ViewPerformance.getInstance();
// Start monitoring
viewPerformance.startMonitoring();
// Your application code here
// Stop monitoring when done
viewPerformance.stopMonitoring();
```
--------------------------------
### Record Multiple Metric Types in Elixir
Source: https://github.com/hydepwns/raxol/blob/master/docs/metrics/UNIFIED_METRICS.md
A quick start example showing how to record different types of metrics (performance, resource, operation, custom) using their respective `UnifiedCollector` functions.
```elixir
# Record different types of metrics
UnifiedCollector.record_performance(:frame_time, 16)
UnifiedCollector.record_resource(:memory_usage, 1024)
UnifiedCollector.record_operation(:buffer_write, 5)
UnifiedCollector.record_custom("user.login_time", 150)
```
--------------------------------
### Progress Bar Demo
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/showcase/README.md
A comprehensive demo of progress indicators and loading states in Raxol applications.
```elixir
mix run examples/showcase/progress_bar_demo.exs | cat
```
--------------------------------
### Raxol Component Library Overview (APIDOC)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/overview.md
Documentation for Raxol's suite of pre-built, customizable UI components, detailing the `Base.Component` behaviour, focus management, and existing component types.
```APIDOC
Component Library (`lib/raxol/ui/components/`)
- Suite of pre-built, customizable components using `Base.Component` behaviour.
- Existing Components: Text inputs (single, multi-line), Selection (select_list, dropdown), Progress (spinner, progress_bar), Data display (table), etc.
- Focus management system (`Core.FocusManager`).
- Standardized component API (`Base.Component`).
- Comprehensive component testing infrastructure.
- Future: Dedicated navigation components (tabs, pagination), password input variant.
```
--------------------------------
### Elixir Mock Verification with Mox
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/testing.md
This Elixir example illustrates how to explicitly verify mock calls using `Mox.verify!`. This ensures that expected interactions with mocked dependencies have occurred, which is crucial for testing system interactions.
```elixir
# Verify mock calls
Mox.verify!(MyMock)
```
--------------------------------
### Implement Raxol Plugin Behaviour
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/04_extending_raxol/plugin_development.md
Defines the core structure for a Raxol plugin, including initialization, termination, command registration, and command handling. This example shows the basic implementation of the `Raxol.Core.Runtime.Plugins.Plugin` behaviour.
```Elixir
defmodule MyPlugin do
@behaviour Raxol.Core.Runtime.Plugins.Plugin
@impl true
def init(config), do: {:ok, %{initial_state: :ok}}
@impl true
def terminate(reason, state), do: :ok
@impl true
def get_commands() do
[%{namespace: :my_plugin, name: :do_something, arity: 1, description: "Action."}]
end
@impl true
def handle_command({:my_plugin, :do_something}, args, state) do
# Handle command...
{:reply, :ok, state}
end
def handle_command(_command, _args, state), do: {:error, :unknown_command, state}
end
```
--------------------------------
### Remove macOS Quarantine Attribute for Raxol
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command removes the `com.apple.quarantine` extended attribute from the Raxol application. This can resolve 'App is damaged' warnings that sometimes appear on macOS when running newly downloaded applications.
```bash
xattr -d com.apple.quarantine /path/to/raxol
```
--------------------------------
### Execute Raxol Visualization Performance Benchmarks
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/components/visualization/testing-guide.md
Commands to run performance benchmarks for Raxol's visualization components with varying data sizes (small, medium, large, production) to assess rendering speed and efficiency.
```bash
mix benchmark.visualization small # 1,000 data points
mix benchmark.visualization medium # 10,000 data points
mix benchmark.visualization large # 100,000 data points
mix benchmark.visualization production # 1,000,000 data points
```
--------------------------------
### Add Raxol as Elixir Mix Dependency
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This snippet shows how to declare Raxol as a dependency in your Elixir project's `mix.exs` file. It specifies the `raxol` package with a version constraint of `~> 0.5.0`, ensuring compatibility.
```elixir
def deps do
[
{:raxol, "~> 0.5.0"}
]
end
```
--------------------------------
### Elixir: Initializing and Accessing Colors from Raxol.Core.ColorSystem
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/02_core_concepts/theming.md
Illustrates how to initialize the Raxol color system and retrieve semantic and UI-specific colors. This system ensures accessibility compliance and provides consistent color usage across the application. It allows fetching base colors, variations like hover states, and component-specific colors.
```elixir
Raxol.Core.ColorSystem.init()
color = Raxol.Core.ColorSystem.get_color(:primary)
hover_color = Raxol.Core.ColorSystem.get_color(:primary, :hover)
button_color = Raxol.Core.ColorSystem.get_ui_color(:primary_button)
```
--------------------------------
### Customize Raxol Accessibility Options (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/accessibility/accessibility_guide.md
This example shows how to enable the accessibility feature with custom options, allowing configuration of high contrast, reduced motion, and large text modes directly during feature activation.
```Elixir
Raxol.Core.UXRefinement.enable_feature(:accessibility,
high_contrast: true,
reduced_motion: true,
large_text: true
)
```
--------------------------------
### Resolve Raxol Permission Issues
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
This command makes the Raxol executable file runnable by adding execute permissions. It is a common solution for 'Permission Issues' where the system prevents the application from running due to insufficient rights.
```bash
chmod +x /path/to/raxol
```
--------------------------------
### Register Global Keyboard Shortcut in Raxol (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/accessibility/accessibility_guide.md
This example demonstrates how to register a global keyboard shortcut, associating a key combination with a specific action. It includes defining the shortcut, the function to execute, and a descriptive label for documentation.
```Elixir
# Register global shortcut
Raxol.Core.UXRefinement.register_shortcut("Ctrl+S", :save, fn ->
save_document()
Raxol.Core.UXRefinement.announce("Document saved")
end, description: "Save document")
```
--------------------------------
### Set UTF-8 Locale on Linux
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/01_getting_started/install.md
These commands generate and set the system locale to `en_US.UTF-8` on Linux. This is crucial for proper Unicode and emoji support in Raxol's terminal output, preventing display issues with special characters.
```bash
locale-gen en_US.UTF-8
update-locale LANG=en_US.UTF-8
```
--------------------------------
### Execute Raxol Visualization Test Scripts
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/03_components_and_layout/components/visualization/testing-guide.md
Commands to run automated tests for Raxol's visualization components in both VS Code Extension and Native Terminal environments, including a general command for performance benchmarks.
```bash
./scripts/test_vscode_visualization.exs
./scripts/test_terminal_visualization.exs
mix benchmark.visualization [small|medium|large|production]
```
--------------------------------
### Elixir Function Documentation with @doc
Source: https://github.com/hydepwns/raxol/blob/master/docs/components/style_guide.md
Demonstrates how to document Elixir functions using the @doc attribute, including parameters, return values, and examples. It also shows a basic handle_event implementation for input changes.
```Elixir
@doc """
Handles text input changes.
## Parameters
* `event` - The input change event containing:
* `:type` - Event type (`:change`, `:focus`, `:blur`)
* `:value` - New input value
* `state` - Current component state
## Returns
* `{new_state, commands}` - Updated state and commands
## Examples
iex> handle_event(%{type: :change, value: "new value"}, %{value: "old"})
{%{value: "new value"}, []}
"""
@impl true
def handle_event(%{type: :change, value: value}, state) do
{put_in(state, [:value], value), []}
end
```
--------------------------------
### Test Raxol Event System with ExUnit Assertions (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/roadmap/architecture/EventSystemExamples.md
This comprehensive example demonstrates testing event-driven logic in Raxol using ExUnit.Case and Raxol.Test.Integration.Assertions. It includes tests for waiting on runtime initialization, verifying plugin load attempts, and confirming accessibility preference updates, showcasing event-based synchronization in tests.
```Elixir
defmodule MyTest do
use ExUnit.Case
import Raxol.Test.Integration.Assertions
test "waits for runtime initialization" do
# Start the runtime
{:ok, _pid} = Raxol.Runtime.start_link([])
# Wait for initialization event
assert_receive {:runtime_initialized, _runtime_pid}, 1000
# Continue with test
# ...
end
test "verifies plugin loading" do
# Start the plugin manager
{:ok, _pid} = Raxol.Core.Runtime.Plugins.Manager.start_link([runtime_pid: self()])
# Attempt to load a plugin
Raxol.Core.Runtime.Plugins.Manager.load_plugin("my_plugin", %{})
# Verify plugin load attempt
assert_receive {:plugin_load_attempted, "my_plugin"}, 1000
end
test "checks accessibility preferences" do
# Set accessibility preferences
Raxol.Core.Accessibility.Preferences.set_large_text(true)
# Verify text scale update
assert_receive {:text_scale_updated, 1.5}, 1000
end
end
```
--------------------------------
### Enable and Check High Contrast Mode in Raxol (Elixir)
Source: https://github.com/hydepwns/raxol/blob/master/examples/guides/05_development_and_testing/development/planning/accessibility/accessibility_guide.md
This example demonstrates how to programmatically enable high contrast mode to improve visibility for users with visual impairments. It also shows how to check the current status of high contrast mode.
```Elixir
# Enable high contrast mode
Raxol.Core.Accessibility.set_high_contrast(true)
# Check if high contrast is enabled
high_contrast = Raxol.Core.Accessibility.high_contrast_enabled?()
```
--------------------------------
### Raxol Rendering Capabilities
Source: https://github.com/hydepwns/raxol/blob/master/examples/snippets/basic/README.md
Shows various rendering capabilities of Raxol, including layout, styling, and component usage.
```Elixir
mix run examples/basic/rendering.exs | cat
```