TermUI.Helpers.BorderHelper (TermUI v1.0.0)

View Source

Helper functions for rendering borders using CharacterSet.

This module provides convenience functions for common border rendering patterns, eliminating code duplication across widgets that draw borders.

All functions use the current CharacterSet to ensure correct character selection based on terminal capabilities (Unicode or ASCII).

Usage

import TermUI.Helpers.BorderHelper

# Draw a horizontal line
line = horizontal_line(20)
# => "────────────────────" (Unicode) or "--------------------" (ASCII)

# Draw a box top
top = box_top(20)
# => "┌──────────────────┐" (Unicode) or "+------------------+" (ASCII)

Integration with Widgets

Widgets can use these helpers to render borders consistently:

def render_border(state, area) do
  import TermUI.Helpers.BorderHelper

  stack(:vertical, [
    text(box_top(area.width)),
    # ... content ...
    text(box_bottom(area.width))
  ])
end

Summary

Functions

bordered_row(content, width, opts \\ [])

Renders a complete row with left and right borders.

box_bottom(width)

Renders the bottom border of a box.

box_bottom_round(width)

Renders the bottom border of a box with rounded corners.

box_top(width)

Renders the top border of a box.

box_top_round(width)

Renders the top border of a box with rounded corners.

horizontal_line(width)

Renders a horizontal line of the specified width.

horizontal_line_heavy(width)

Renders a heavy horizontal line of the specified width.

left_border(content \\ "")

Renders a left border character with optional content.

right_border(content \\ "")

Renders a right border character with optional content.

vertical_line(height)

Renders a vertical line of the specified height.

Functions

bordered_row(content, width, opts \\ [])

@spec bordered_row(String.t(), non_neg_integer(), keyword()) :: String.t()

Renders a complete row with left and right borders.

Format: │ + padded content + │

The content is padded to fill the inner width.

Parameters

  • content - Content to display between borders
  • width - Total width including borders (minimum 2)
  • opts - Options:
    • :pad - Padding character (default: " ")
    • :align - :left, :right, or :center (default: :left)

Examples

iex> bordered_row("Hello", 12)
"│Hello     │"

iex> bordered_row("Hi", 10, align: :center)
"│   Hi    │"

box_bottom(width)

@spec box_bottom(non_neg_integer()) :: String.t()

Renders the bottom border of a box.

Format: └ + horizontal line + ┘

Parameters

  • width - Total width including corners (minimum 2)

Examples

iex> box_bottom(10)
"└────────┘"  # Unicode mode

iex> Application.put_env(:term_ui, :character_set, :ascii)
iex> box_bottom(10)
"+--------+"

box_bottom_round(width)

@spec box_bottom_round(non_neg_integer()) :: String.t()

Renders the bottom border of a box with rounded corners.

Format: ╰ + horizontal line + ╯

Parameters

  • width - Total width including corners (minimum 2)

Examples

iex> box_bottom_round(10)
"╰────────╯"  # Unicode mode

box_top(width)

@spec box_top(non_neg_integer()) :: String.t()

Renders the top border of a box.

Format: ┌ + horizontal line + ┐

Parameters

  • width - Total width including corners (minimum 2)

Examples

iex> box_top(10)
"┌────────┐"  # Unicode mode

iex> Application.put_env(:term_ui, :character_set, :ascii)
iex> box_top(10)
"+--------+"

box_top_round(width)

@spec box_top_round(non_neg_integer()) :: String.t()

Renders the top border of a box with rounded corners.

Format: ╭ + horizontal line + ╮

Parameters

  • width - Total width including corners (minimum 2)

Examples

iex> box_top_round(10)
"╭────────╮"  # Unicode mode

horizontal_line(width)

@spec horizontal_line(non_neg_integer()) :: String.t()

Renders a horizontal line of the specified width.

Uses the current CharacterSet's horizontal line character.

Parameters

  • width - Width of the line in characters

Examples

iex> horizontal_line(5)
"─────"  # Unicode mode

iex> Application.put_env(:term_ui, :character_set, :ascii)
iex> horizontal_line(5)
"-----"

horizontal_line_heavy(width)

@spec horizontal_line_heavy(non_neg_integer()) :: String.t()

Renders a heavy horizontal line of the specified width.

Uses the current CharacterSet's heavy horizontal line character.

Parameters

  • width - Width of the line in characters

Examples

iex> horizontal_line_heavy(5)
"━━━━━"  # Unicode mode

left_border(content \\ "")

@spec left_border(String.t()) :: String.t()

Renders a left border character with optional content.

Format: │ + content

Parameters

  • content - Optional content to append after the border (default: "")

Examples

iex> left_border()
"│"

iex> left_border(" Hello")
"│ Hello"

right_border(content \\ "")

@spec right_border(String.t()) :: String.t()

Renders a right border character with optional content.

Format: content + │

Parameters

  • content - Optional content to prepend before the border (default: "")

Examples

iex> right_border()
"│"

iex> right_border("Hello ")
"Hello │"

vertical_line(height)

@spec vertical_line(non_neg_integer()) :: [String.t()]

Renders a vertical line of the specified height.

Returns a list of strings, one per line.

Parameters

  • height - Height of the line in characters

Examples

iex> vertical_line(3)
["│", "│", "│"]  # Unicode mode