# `Alaja.Helpers`
[🔗](https://github.com/Lorenzo-SF/alaja/blob/2.1.0/lib/alaja/helpers.ex#L1)

High-level drawing helpers for TUI applications.

Provides functions for common UI patterns like:
- Braille sparklines
- Progress bars with color gradients
- Box drawing (single and double border)
- Color interpolation utilities

Note: Basic ANSI escape functions have been moved to `Alaja.ANSI`.
This module now focuses on high-level helpers only.

# `box`

Draw a box with single-line border.

## Parameters
  - x, y: Starting position (1-indexed)
  - w, h: Width and height
  - title: Optional title (default: "")
  - color: RGB color as {r, g, b} (default: {100, 140, 200})

## Returns
A list of {x, y, text} tuples for rendering.

## Example
    iex> Helpers.box(1, 1, 40, 10, "My Box", {100, 140, 200})
    [{1, 1, "╭──────────────────────────────────────╮"}, ...]

# `braille_spark`

Generate a braille sparkline from a list of values (0-100).

## Parameters
  - values: List of numbers (0-100)
  - width: Maximum number of braille characters to display

## Returns
A string of braille characters representing the data.

## Example
    iex> Helpers.braille_spark([10, 50, 90, 30], 4)
    "⣤ ⣿ ⣤ ⣀"

# `double_box`

Draw a box with double-line border.

## Parameters
  - x, y: Starting position (1-indexed)
  - w, h: Width and height
  - title: Optional title (default: "")
  - color: RGB color as {r, g, b} (default: {180, 130, 80})

## Returns
A list of {x, y, text} tuples for rendering.

## Example
    iex> Helpers.double_box(1, 1, 40, 10, "Workers", {180, 130, 80})
    [{1, 1, "╔══════════════════════════════════════╗"}, ...]

# `lerp`

Linear interpolation between two RGB colors.

## Parameters
  - c1: Starting color {r, g, b}
  - c2: Ending color {r, g, b}
  - t: Interpolation factor (0.0 to 1.0)

## Returns
Interpolated color as {r, g, b}.

## Example
    iex> Helpers.lerp({0, 0, 0}, {255, 255, 255}, 0.5)
    {127, 127, 127}

# `progress_bar`

Generate a progress bar with color gradient.

## Parameters
  - pct: Percentage (0-100)
  - width: Width of the bar in characters
  - color_start: Starting color as {r, g, b}
  - color_end: Ending color as {r, g, b}

## Returns
A string containing the progress bar with percentage display.

## Example
    iex> Helpers.progress_bar(75, 20, {80, 140, 255}, {200, 100, 255})
    "███████████████████░░░ 75%"

# `safe_string_to_atom`

```elixir
@spec safe_string_to_atom(String.t()) :: {:ok, atom()} | {:error, String.t()}
```

Safely converts a string to an existing atom.

Wraps `String.to_existing_atom/1` in a try/rescue to prevent
atom table exhaustion from untrusted input.

Returns `{:ok, atom}` on success, `{:error, message}` if the atom does not exist.

---

*Consult [api-reference.md](api-reference.md) for complete listing*